Skip to main content
An OAuth application acts on behalf of a specific user. It holds an access token that carries only the scopes that user consented to, and every call it makes is evaluated against that user’s own permissions in Chamelio. If the user cannot open a task in the web application, the application cannot read it through the API either. Chamelio implements OAuth 2.1 with PKCE. Tokens are opaque bearer tokens.

​
Base URL

The authorization server itself lives one level up, at https://platform.chamelio.ai/oauth/....

​
Authentication

Send the access token as a bearer token:
These endpoints accept bearer tokens only. Sending an X-API-Key header to a /v2 path returns 401 Unauthorized - the API key surface is documented under API Keys.

​
How it works

1

Register an application

An organization admin registers the application in Developer settings and chooses the scopes it may ever request. This yields a client_id, and for confidential clients a client_secret shown only once. See Managing Applications.
2

Send the user to consent

Redirect the user to /oauth/authorize with a PKCE challenge. They review the requested scopes and approve, and you receive a single-use authorization code.
3

Exchange the code for a token

Call /oauth/token with the code and your PKCE verifier to get an access token.
4

Call the API

Use the token against /v2 endpoints. Each endpoint states the scope it requires.

​
Scopes

Scopes follow the resource:action convention and are requested as a space-delimited string.
:write does not imply :read. An application that both reads and writes tasks must request tasks:read tasks:write.
An application’s allowed_scopes may accept documents:read, documents:write, files:write and mcp:read as well. Those are reserved for endpoints that do not exist yet and grant nothing today - requesting them has no effect. Every scope enforced by a live endpoint is listed in the table above.
Note that some task endpoints are gated on files:read rather than tasks:read, because they return file content: listing a task’s files, downloading a step document, and retrieving signed documents. Each endpoint page states its own required scope.

​
Acting as a user

Every /v2 call runs as the user the token was issued to. Two consequences:
  • Permissions are enforced per resource. Reaching a task, workflow, or file the user has no access to returns 403 Forbidden, regardless of scope.
  • Writes are attributed to that user. Comments are posted as them, tasks are initiated as them, and users or groups they create are recorded as created by them. Request body fields that name a different actor - user_email on task endpoints, user on workflow initiation - are ignored.
The one exception is /v2/server/clickwrap/*. The subject of a clickwrap event is user_identifier, an opaque string you supply for your own end user, which is never resolved against Chamelio’s users. Those four endpoints are therefore authorized by organization and scope alone, with no acting user.

​
Client credentials tokens

A client_credentials token acts as the admin who created the application, so it can call /v2 like any other token. Calls are attributed to that admin, and the resources the token can reach are the ones that admin can reach.
Whoever creates a client_credentials application decides what its tokens can see. Create the application as a user whose access matches what the integration actually needs, and remember that deactivating that user revokes its tokens - see 403 Forbidden below.
Tokens issued before application creators were recorded have no user behind them. Those predate the change and are rejected on any /v2 endpoint that acts as a user; request a new token to replace one:

​
Token lifetime

Access tokens do not expire by default. An application can opt into a finite lifetime by setting default_token_ttl_seconds at registration, and only then is a refresh token issued alongside the access token. Refreshing rotates the pair: the old access and refresh tokens are both revoked. client_credentials never receives a refresh token - request a new one instead. Tokens can be revoked individually with /oauth/revoke, and deleting an application revokes every token it ever issued.

​
Rate limiting

OAuth traffic is rate limited per organization, not per token, using a one-minute window. An application may hold many tokens, so the organization is the meaningful unit to throttle. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

​
Error responses

Every /v2 endpoint can return the following. Individual pages document the errors specific to them.

​
401 Unauthorized

The token is missing, unknown, revoked, or expired - or an X-API-Key was sent instead of a bearer token. Responses carry WWW-Authenticate: Bearer.

​
403 Forbidden

Either the token lacks a required scope:
Or the user may not reach the resource:
Or the user the token acts as is no longer an active member of the organization:
That last case revokes the token. Deactivating a user permanently invalidates every access token issued to them, including client_credentials tokens for applications they created. Reactivating the user does not bring the tokens back - issue new ones.

​
404 Not Found

​
422 Unprocessable Entity

The request body failed validation, or the operation was rejected for the state it was in. The detail is either FastAPI’s field-level error array or a specific message describing what to fix.
403 and 404 bodies are intentionally generic. The underlying reason is recorded in Chamelio’s logs rather than returned, so responses cannot be used to probe for resources the user cannot see.

​
Next steps

Get an Access Token

The three supported grants and their parameters

Authorize a User

Start the authorization code flow with PKCE

Managing Applications

Register an application and configure its scopes and redirect URIs

Get Current User

Confirm which user and scopes a token resolves to