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.
Create an access token
Section titled “Create an access token”In the dashboard: Account → Agent access → New token. Or create one from a signed-in session:
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:
curl -H "Authorization: Bearer ot_pat_..." http://localhost:8000/v1/auth/me| Field | Default | Meaning |
|---|---|---|
name | Required | What the token is for. Shown in your token list |
scope | Platform default: read | Caps the token’s permissions; see Scopes |
org_id | None | Limit the token to one of your organizations |
expires_in_days | Platform maximum: 90 days by default | Token lifetime. The platform maximum can be configured |
Scopes
Section titled “Scopes”A scope sets a ceiling on the permissions your role grants in the org the token acts in.
| Scope | Permissions |
|---|---|
read | Read-only permissions |
write | Read-only permissions and day-to-day permissions available to viewer and member roles |
admin | All 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.
Choose the organization
Section titled “Choose the organization”The token acts in this order:
- The org in
org_id, if the token is limited to one. - The org named in the
X-OpenTremor-Orgheader. - 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.
Account actions that require a session
Section titled “Account actions that require a session”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.
Revoke an access token
Section titled “Revoke an access token”In the dashboard: Account → Agent access. Or revoke it from a signed-in session:
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.
Connected apps (OAuth)
Section titled “Connected apps (OAuth)”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.
Set access policies
Section titled “Set access policies”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"}.
| Policy | Effect |
|---|---|
allowed | Tokens act with their own scope |
read_only | Caps tokens at read in this org. A token limited to this org can only be created with read |
forbidden | Refuses 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.