Get an Access Token

POST

/oauth/token

curl --request POST \
  --url https://api.example.com/oauth/token \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=ci_test_4f2aK9mQ7xR1vT8bN3cL6hWd \
  --data client_secret=example

• Your platform's API host

Exchanges your client ID and secret for an Access Token (the OAuth 2.0 client credentials grant, RFC 6749). Send the client ID and secret in a Basic Authorization header, or as client_id and client_secret in the body, not both, and each parameter once. The token lasts 15 minutes; any standard OAuth client library can call this and fetch a new token as each expires.

Errors follow RFC 6749, not the /v1 envelope. Every client ID and secret that proves nothing — an unknown client, a wrong secret, a revoked key — gets the same invalid_client. Token requests are rate limited per client ID and per address.

Authorizations

• ClientSecret
• None

Request Body^required

object

grant_type

required

string

Allowed value: client_credentials

client_id

With client_secret, instead of a Basic header.

string

client_secret

With client_id, instead of a Basic header.

string

The same parameters as a JSON object, for a client that sends JSON.

object

grant_type

required

string

Allowed value: client_credentials

client_id

string

client_secret

string

Responses

200

The token. Every answer here is sent with Cache-Control: no-store and Pragma: no-cache.

Media typeapplication/json

object

access_token

string

token_type

string

Allowed value: Bearer

expires_in

Seconds until it expires.

integer

Example

{
  "token_type": "Bearer",
  "expires_in": 900
}

400

invalid_request (no grant_type, or the client authenticated both ways), or unsupported_grant_type (anything but client_credentials).

Media typeapplication/json

object

error

required

string

Allowed values: invalid_request invalid_client unsupported_grant_type rate_limited

error_description

required

string

Example

{
  "error": "invalid_request"
}

401

invalid_client: the client ID or secret is not valid. Sent with a WWW-Authenticate: Basic header.

Media typeapplication/json

object

error

required

string

Allowed values: invalid_request invalid_client unsupported_grant_type rate_limited

error_description

required

string

Example

{
  "error": "invalid_request"
}

429

rate_limited: too many token requests. Try again shortly.

Media typeapplication/json

object

error

required

string

Allowed values: invalid_request invalid_client unsupported_grant_type rate_limited

error_description

required

string

Example

{
  "error": "invalid_request"
}