v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Exchange a grant for OAuth tokens

Issues an access token and a refresh token in exchange for a valid grant. Three grant types are supported: "authorization_code", "refresh_token", and "urn:ietf:params:oauth:grant-type:device_code".

For "authorization_code" grants, supply code, client, redirect_uri, and optionally code_verifier for PKCE flows. Each authorization code is single-use; consuming it a second time returns invalid_grant.

For "refresh_token" grants, supply refresh_token. The endpoint rotates the refresh token on every call and returns a fresh pair of tokens.

For device-code grants, supply device_code and client. Poll this endpoint after receiving authorization_pending until the user approves or the code expires. Slow down polling if you receive slow_down.

This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding the limit returns HTTP 429 with "error": "too_many_requests".

post/oauth/token

Request body

clientstring

OAuth client ID identifying the application requesting tokens. Required for "authorization_code" and device-code grants.

codestring

Single-use authorization code issued by the authorization endpoint. Required for "authorization_code" grants.

code_verifierstring

PKCE code verifier corresponding to the code_challenge sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.

device_codestring

Device code received from the device authorization endpoint. Required for device-code grants.

grant_typestring required

The OAuth 2.0 grant type. One of "authorization_code", "refresh_token", or "urn:ietf:params:oauth:grant-type:device_code".

redirect_uristring

Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for "authorization_code" grants.

refresh_tokenstring

Refresh token received from a previous token response. Required for "refresh_token" grants. The token is rotated on each successful call.

Example request

{
  "client": "string",
  "code": "string",
  "code_verifier": "string",
  "device_code": "string",
  "grant_type": "string",
  "redirect_uri": "https://example.com",
  "refresh_token": "string"
}

Response

Successful response

access_tokenstring required

Bearer token used to authenticate API requests. Include this value in the Authorization: Bearer <token> header.

expires_ininteger required

Number of seconds until the access token expires.

refresh_tokenstring

Token that can be exchanged for a new access token once the current one expires. null if the grant type does not issue refresh tokens.

scopestring

Space-separated list of scopes granted to the access token. null if scope was not included in the grant request.

token_typestring required

Token type. Always "Bearer".

Example response

{
  "access_token": "string",
  "expires_in": 3600,
  "refresh_token": "string",
  "scope": "read write",
  "token_type": "Bearer",
  "user": {
    "alias": "jdoe",
    "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
    "app_name": "Example Name",
    "email": "user@example.com",
    "id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
    "is_system_user": true,
    "metadata": {
      "key": "value"
    },
    "name": "Example Name",
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "org_name": "Example Name",
    "org_role": "member",
    "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
    "sandbox_name": "Example Name"
  }
}