API Tokens
An API token is a Bearer credential that acts as you. Use it where a sign-in is not possible: an MCP client without OAuth, DevKit, CI, a script, or an integration you hand to someone else.
Open Organization → API Tokens in the sidebar, or go to /settings/api-tokens. The page is titled MCP and API tokens.
What every token does
| Rule | Behavior |
|---|---|
| One organization | A token works only in the organization it was created in. Switching organization in the web app does not move it. To work in another organization, switch to it and create a token there. |
| Acts as you | A token can do only what you can do in that organization. If your role changes, the token changes with it. If you leave the organization, the token stops working. |
| Shown once | The value starts with lt_ and is shown once, right after you create it. Copy it then. |
| Optional expiry | No expiry, 24 hours, 7 days, 30 days, 90 days or 1 year. A token you give to a third party should expire. |
The list shows the tokens you created in the current organization, with created, last used and expiry dates.
Create a token
- Click + Issue new token.
- Enter a Token name, such as
DevKit,Claude MCPorCI pipeline. Names are unique per person. - Optional: tick Only allow the workflows listed below to limit the token. See Limit a token to specific workflows.
- Pick Expires.
- Click Generate token, copy the value, then click I have saved the token.
Send it on every request:
Authorization: Bearer lt_…
Limit a token to specific workflows
Leave the box unticked and the token can do everything you can in the organization. Tick it and the token can only start the workflows you list. Use this for anything that should do one job: a partner integration, a webhook bridge, an MCP client that only needs two workflows.
Under Allowed workflows, write one entry per line:
| Entry | Matches |
|---|---|
staff.invoke-actor | That workflow type, exactly |
data.agents | data.agents and every type under it, such as data.agents.list. It does not match data.agentsx. |
A trailing .* is accepted and removed. You can list up to 50 entries.
What a limited token can do
| Allowed | Refused | |
|---|---|---|
| Start | Workflow types on the list | Any other type: 403, code API_TOKEN_WORKFLOW_NOT_ALLOWED |
| Runs | Status, history, live updates, DAG status, retry and search, for runs of listed types | Runs of any other type read as not found (404) |
| Catalog | Listing types, schemas and definitions shows only listed types | The schema of any other type is 404 |
| Other endpoints | — | Stuck-run lists, force-terminate, resolving a gate, prerequisites and field options: 403, code RESTRICTED_TOKEN_NOT_ALLOWED |
| Rest of the platform | — | Account, member, token-management and organization-switch APIs refuse a limited token |
A limited token is always tied to the organization it was created in.
identity.) unless you mean to hand those powers to whoever holds the token.Check what a token holds with GET /api/auth/me. A limited token reports "restricted": true and its allowed_workflow_prefixes:
curl -sS https://workflow-api.orkestia.dev/api/auth/me \
-H "Authorization: Bearer $ORKESTIA_TOKEN"
The same limits apply through the MCP server: the catalog tools list only the allowed workflows, and starting any other workflow is refused.
Manage a token
Open Manage on a token row.
| Action | What it does |
|---|---|
| Rename | Changes the name only. |
| Rotate | Issues a new value and invalidates the current one right away. Not available for a limited token: issue a new limited token, then revoke the old one. |
| Narrow access | Limited tokens only. Untick workflows the token should no longer run, or set or shorten its expiry. Access can only be reduced. To grant more, issue a new token. Runs of a removed workflow read as not found from then on, even if this token started them. |
| Revoke | Permanent. Anything using the token loses access immediately. |
A limited token's row shows a tag such as Restricted to data.agents or Restricted to 3 workflows. Hover it to see the full list.
Errors
| Status | Code | Meaning | Fix |
|---|---|---|---|
403 | API_TOKEN_WORKFLOW_NOT_ALLOWED | The token is limited and the workflow is not on its list. The response names the workflow_type. | Issue a new token that lists it. |
403 | RESTRICTED_TOKEN_NOT_ALLOWED | A limited token called an endpoint limited tokens cannot use. | Use an unlimited token, or a person's sign-in, for that call. |
404 | — | The run or workflow type is outside the token's list (or does not exist). | Check the list with /api/auth/me. |
401 | API_TOKEN_EXPIRED | The token passed its expiry. | Issue a new token. |
401 | API_TOKEN_MEMBERSHIP_REVOKED | You are no longer a member of the token's organization. | An owner or admin can invite you again. |
401 | API_TOKEN_ORG_UNBOUND | An older token that is not tied to an organization, used by someone in several organizations. | Create a new token in the organization you want. |
Good practice
- One token per tool or integration, named after it. Revoking one then breaks nothing else.
- Give anything outside your team a limited token with an expiry.
- Keep tokens in environment variables or a secret store, never in a browser app or a committed file.
- Prefer OAuth sign-in for MCP clients that support it. See Connect an AI assistant.