Get an Access Token

The token endpoint issues the bearer tokens used on /v2 endpoints. It supports three grants: authorization_code, client_credentials, and refresh_token.

Endpoint

POST /oauth/token

Authentication

The request authenticates your application, not a user. Send credentials in the form body (client_secret_post):

Confidential clients must send client_id and a matching client_secret.
Public clients send client_id only and prove possession through PKCE.

HTTP Basic authentication is not supported. Client credentials must be form fields in the request body.

Request Body

Content type: application/x-www-form-urlencoded

Parameter	Type	Required	Description
`grant_type`	string	Yes	`authorization_code`, `client_credentials`, or `refresh_token`
`client_id`	string	Yes	Your application’s client ID (`cid_...`)
`client_secret`	string	Conditional	Required for confidential clients. Omit for public clients
`code`	string	Conditional	Required for `authorization_code` - the code from the authorize redirect
`redirect_uri`	string	Conditional	Required for `authorization_code`. Must match the value used at `/oauth/authorize` exactly
`code_verifier`	string	Conditional	Required for `authorization_code` - the PKCE verifier whose SHA-256 you sent as `code_challenge`
`refresh_token`	string	Conditional	Required for `refresh_token`
`scope`	string	No	`client_credentials` only. Space-delimited subset of the application’s allowed scopes. Defaults to all of them when omitted

Grants

authorization_code
client_credentials
refresh_token

Exchanges a single-use code from /oauth/authorize for a token bound to the user who consented. This is the grant to use for anything calling /v2.Required: grant_type, client_id, code, redirect_uri, code_verifier (plus client_secret for confidential clients).The granted scopes are the ones the user approved - you cannot widen them here.

Authenticates the application itself, with no end user involved in the exchange. The token acts as the admin who created the application and carries that admin’s access.Required: grant_type, client_id, client_secret. The application must be a confidential client and must have client_credentials among its grant types.

The creating admin sets the ceiling on what these tokens can reach, and deactivating that user revokes them. See Client credentials tokens.

No refresh token is ever issued for this grant; request a new access token instead.

Exchanges a refresh token for a new access token, carrying over the original scopes and user.Required: grant_type, client_id, refresh_token (plus client_secret for confidential clients).

Refreshing rotates the pair: the old access token and the old refresh token are both revoked immediately. Store the new refresh_token from the response - the previous one no longer works.

A refresh token only exists if the application set default_token_ttl_seconds. Applications without a token TTL receive non-expiring access tokens and no refresh token.

Request Example

curl -X POST "https://platform.chamelio.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=cid_your_client_id" \
  -d "client_secret=ca_your_client_secret" \
  -d "code=ca_single_use_code" \
  -d "redirect_uri=https://your-app.example.com/callback" \
  -d "code_verifier=your_pkce_code_verifier"

import requests

url = "https://platform.chamelio.ai/oauth/token"
data = {
    "grant_type": "authorization_code",
    "client_id": "cid_your_client_id",
    "client_secret": "ca_your_client_secret",
    "code": "ca_single_use_code",
    "redirect_uri": "https://your-app.example.com/callback",
    "code_verifier": "your_pkce_code_verifier",
}

response = requests.post(url, data=data)
token = response.json()
print(token["access_token"])

const response = await fetch('https://platform.chamelio.ai/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: 'cid_your_client_id',
    client_secret: 'ca_your_client_secret',
    code: 'ca_single_use_code',
    redirect_uri: 'https://your-app.example.com/callback',
    code_verifier: 'your_pkce_code_verifier'
  })
});

const token = await response.json();
console.log(token.access_token);

Response

Success Response

Status Code: 200 OK

{
  "access_token": "ca_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz",
  "token_type": "Bearer",
  "scope": "tasks:read tasks:write",
  "expires_in": 3600,
  "refresh_token": "ca_AbCdEfGhIjKlMnOpQrStUvWxYz123xYz"
}

For an application without a token TTL, the response omits both optional fields entirely:

{
  "access_token": "ca_xYz123AbCdEfGhIjKlMnOpQrStUvWxYz",
  "token_type": "Bearer",
  "scope": "tasks:read tasks:write"
}

Response Fields

Field	Type	Description
`access_token`	string	The bearer token to send as `Authorization: Bearer ...`
`token_type`	string	Always `Bearer`
`scope`	string	Space-delimited scopes actually granted to this token
`expires_in`	integer	Lifetime in seconds. Omitted when the token does not expire
`refresh_token`	string	Omitted unless the application set a finite token TTL, and never present for `client_credentials`

Error Responses

Errors follow the OAuth error format rather than Chamelio’s usual detail body:

{
  "error": "invalid_grant",
  "error_description": "PKCE verification failed"
}

401 Unauthorized

`error`	Reason
`invalid_client`	`client_id` missing, unknown, or inactive; wrong or missing `client_secret` for a confidential client; or a public client attempting `client_credentials`

400 Bad Request

`error`	Reason
`invalid_request`	A required parameter for the grant is missing
`invalid_grant`	The code or refresh token is unknown, already used, expired, revoked, issued to a different client, has a mismatched `redirect_uri`, or failed PKCE verification
`unauthorized_client`	The application is not allowed the requested grant
`invalid_scope`	Requested scope is unknown or exceeds the application’s allowed scopes
`unsupported_grant_type`	`grant_type` is not one of the three supported values

Notes

Store access and refresh tokens as securely as passwords. Chamelio keeps only a hash, so a token value cannot be recovered - losing it means requesting a new one.

Scopes are fixed at issuance. To gain an additional scope, send the user through /oauth/authorize again with the wider scope value.

Verify a fresh token with GET /v2/users/user-info - it echoes back the user, organization, and granted scopes the token resolves to.

Use Cases

Completing user sign-in - Turn an authorization code into a usable token
Keeping a session alive - Rotate a short-lived token before it expires
Confirming a credential - Check that a client ID and secret pair still authenticate

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Request Body

Grants

Request Example

Response

Success Response

Response Fields

Error Responses

401 Unauthorized

400 Bad Request

Notes

Use Cases

​Endpoint

​Authentication

​Request Body

​Grants

​Request Example

​Response

​Success Response

​Response Fields

​Error Responses

​401 Unauthorized

​400 Bad Request

​Notes

​Use Cases

Endpoint

Authentication

Request Body

Grants

Request Example

Response

Success Response

Response Fields

Error Responses

401 Unauthorized

400 Bad Request

Notes

Use Cases