Getting started

Authentication

One bearer token, reaching only the workspaces you chose for it, limited to the scopes you granted it. The same token authenticates the REST API, the MCP server and the agent skill.

The header

Send the token as a bearer credential on every request. Tokens are prefixed eko_ followed by 48 hex characters.

http

Authorization: Bearer eko_a1b2c3d4e5f6...

Scope	Grants	Acts publicly
`read`	Accounts, posts, post stats, comments	No
`write`	Create drafts and scheduled posts	Not immediately
`publish`	Publish a post the moment it is created	Yes
`engage`	Reply to comments as your accounts	Yes

Everything a write-only token creates stays reviewable in the app before it goes out. publish and engage remove that window — a mistake is public and permanent. For an agent you are still evaluating, leave both off.

Workspace isolation

A token reaches only the workspaces ticked when it was created — the current one by default. There is no parameter anywhere in the API to name a workspace outside that set: it is not a permission check that could be bypassed, the capability does not exist. An account reference that resolves nowhere inside the set is refused with the same message as one that does not exist, so a token cannot be used to probe for accounts it cannot see.

The reach is chosen rather than global on purpose. A key ends up in .env files, CI logs and third-party MCP clients, and for the URL variant it sits in the URL itself. Global by default would only buy convenience, and could cost every client at once.

So: tick every workspace for your own key and stop thinking about it; give a contractor a key that covers only their client. You can only grant a key access to workspaces you own or administer.

Reads say where each row comes from

When a key covers several workspaces, every account, post and comment it returns carries the workspace it belongs to — otherwise an agency key would merge two clients into one undifferentiated list. Writes stay singular: one post lives in one workspace, so accounts from two are refused rather than mixed.

How tokens are stored

The raw key is returned exactly once, at creation.
Only a SHA-256 hash is stored, so a database leak does not leak usable keys.
The interface shows a prefix (eko_a1b2c3…) so you can tell tokens apart.
Last-used time is recorded, which is the fastest way to spot a token nobody needs.

Revoking

Revoke from Settings → Developers. It applies to the very next request — there is no cache to wait out. Revoked tokens cannot be restored.

Tokens are also revoked automatically when:

the person who created them is removed from a workspace — the key loses that workspace and keeps the others, and is refused outright once none are left;
they are demoted below admin, which is treated the same way: holding a key requires the role that could have created it;
the workspace or the account is deleted.

Limits on tokens

Limit	Value
Active tokens reaching one workspace	10
Who can create them	Owner and admin only
Requests per token	120 / minute — see Rate limits

Tokens in a URL

Some MCP clients cannot send custom headers, so the MCP server also accepts the key as a path segment. That URL is the credential: it belongs in a password manager, not in a shared document or a screenshot. See MCP server.