Skip to content
DashboardWebsite

Access tokens for agents

Just want to do it in the dashboard? See the guide: Give your coding agent or a script access or Turn agent access on or off.

An access token lets an agent or script act as you, within the permissions of your role and the token’s scope. For example, you can create one for Claude Code, Cursor, or a scheduled job.

Use an API key for a CI job or shared bot. An API key belongs to an org, not to a person.


In the dashboard: Account → Agent access → New token. Or create one from a signed-in session:

Terminal window
curl -X POST http://localhost:8000/v1/auth/me/access-tokens \
-H "Cookie: mcp_session=..." -H "Content-Type: application/json" \
-d '{"name": "Claude Code", "scope": "read", "expires_in_days": 30}'

The response includes the token (ot_pat_…) once. Store it where the agent can read it, then send it as a bearer token:

Terminal window
curl -H "Authorization: Bearer ot_pat_..." http://localhost:8000/v1/auth/me
FieldDefaultMeaning
nameRequiredWhat the token is for. Shown in your token list
scopePlatform default: readCaps the token’s permissions; see Scopes
org_idNoneLimit the token to one of your organizations
expires_in_daysPlatform maximum: 90 days by defaultToken lifetime. The platform maximum can be configured

A scope sets a ceiling on the permissions your role grants in the org the token acts in.

ScopePermissions
readRead-only permissions
writeRead-only permissions and day-to-day permissions available to viewer and member roles
adminAll permissions your role grants. For a platform admin, this scope also preserves platform-admin access

GET /v1/auth/me includes the token’s current permissions.


The token acts in this order:

  1. The org in org_id, if the token is limited to one.
  2. The org named in the X-OpenTremor-Org header.
  3. The org you last used. If that org is no longer active for you, the token uses your first active membership.

You must be an active member of the selected org. A token limited to one org returns 403 if the header names another org.


An access token cannot change account settings or manage access tokens. These actions require a signed-in session: changing your password or 2FA, editing your profile, linking a sign-in provider, accepting an invitation, switching the session’s org, leaving or creating an org, and creating, listing, or revoking access tokens. A platform admin’s token cannot grant or revoke platform-admin access.


In the dashboard: Account → Agent access. Or revoke it from a signed-in session:

Terminal window
curl -X DELETE http://localhost:8000/v1/auth/me/access-tokens/<token_id> -H "Cookie: mcp_session=..."

A token also stops working when:

  • You change or reset your password, or an admin signs you out everywhere.
  • Your account is deactivated, or you are no longer an active member of the org it acts in.
  • It expires.
  • An org admin forbids tokens in the org, or a platform admin turns tokens off.

Hosted clients such as the Claude.ai and ChatGPT connectors use OAuth instead of a pasted token. The client opens an OpenTremor page, where you sign in, choose a scope and optionally an org, then approve access. You do not copy a token.

The client receives a token that lasts one hour and refreshes it. The same scope and org policies apply. In the dashboard: Account → Agent access → Connected apps. Select Disconnect to remove an app and its tokens. Signing out everywhere disconnects all connected apps.

For an operator: the platform MCP advertises the API as its authorization server when MCP_PUBLIC_URL and OPENTREMOR_PUBLIC_API_URL are set. See OpenTremor-platform#0032.


Organization. An org admin sets whether members’ tokens can act in the org. In the dashboard: Organization → Access → Service Accounts → Agent access. Or use PUT /v1/orgs/{org_id}/agent-access with a JSON body such as {"policy": "read_only"}.

PolicyEffect
allowedTokens act with their own scope
read_onlyCaps tokens at read in this org. A token limited to this org can only be created with read
forbiddenRefuses token requests in this org with 403

The policy requires the agent_access:manage permission (admin by default). API keys are not affected.

Platform. A platform admin configures the agent_access settings section: tokens_enabled, max_token_days, and default_token_scope. See Platform Admin.

See OpenTremor-platform#0030 for the reasoning.