Exchange Credentials

Exchange credentials for an access token using one of the supported OAuth2 grant types.

Endpoint

/api/v1/tokens

Method

POST

Headers

Header	Required	Description
`Content-Type`	Yes	`application/x-www-form-urlencoded`
`Authorization`	Conditional	Required for `client_credentials` grant. Must be a Base64-encoded Basic auth header: `Basic base64(client_id:client_secret)`

Request Body

Field	Type	Required	Description
`grant_type`	`string`	Yes	One of: `authorization_code`, `refresh_token`, `client_credentials`
`client_id`	`string`	Conditional	Required when `grant_type` is `authorization_code` or `refresh_token`
`authorization_code`	`string`	Conditional	Required when `grant_type` is `authorization_code`
`redirect_uri`	`string`	Conditional	Required when `grant_type` is `authorization_code`
`code_verifier`	`string`	Conditional	Required when `grant_type` is `authorization_code` (PKCE)
`refresh_token`	`string`	Conditional	Required when `grant_type` is `refresh_token`
`state`	`string`	No	Optional state parameter

Examples

Authorization Code Grant

curl --request POST \
  --url https://auth.roled.id/api/v1/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'authorization_code=6qxJpdxpyuAoSpfzkEbJUpJvBoncYM3Cnxfmj4WznZty7...' \
  --data-urlencode 'client_id=2JRYkzSeBV89itqcU9mraF' \
  --data-urlencode 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk...' \
  --data-urlencode 'redirect_uri=https://example.com/auth/callback' \
  --data-urlencode 'state=e5384378-26b2-45ae-b6a8-3a569a4bff7d'

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...",
    "expires_in": 3600,
    "token_type": "bearer",
    "refresh_token": "M8MmHrhqzcBgUwCQ5enp4wTuRVBgi2txChS44Q3FYJGRgzX...",
    "refresh_token_expires_in": 604800
  }
}

Client Credentials Grant

curl --request POST \
  --url https://auth.roled.id/api/v1/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic MkpVjd5QzdnV0V1enU4QlRFWG9ZNTpzZWNfQmFja...' \
  --data-urlencode 'grant_type=client_credentials'

Refresh Token Grant

curl --request POST \
  --url https://auth.roled.id/api/v1/tokens \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=2JRYkzSeBV89itqcU9mraF' \
  --data-urlencode 'refresh_token=M8MmHrhqzcBgUwCQ5enp4wTuRVBgi2txChS44Q3FYJGRgzX...'

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJo...",
    "expires_in": 3600,
    "token_type": "bearer",
    "refresh_token": "oSpfzkEbJUpJvBoncYM3Cnxfmj4WznZty78YpMd7VSZ7mE4K...",
    "refresh_token_expires_in": 604800
  }
}

Error Codes

Code	HTTP Status	Description
`invalid_params`	400	Missing or invalid request params, headers, or body
`invalid_client`	400	The client ID is invalid
`client_not_active`	400	The client is not active
`project_not_active`	400	The project is not active
`invalid_authorization_code`	400	The authorization code is invalid
`different_authorize_redirect_uri`	400	The redirect URI does not match the one used in the authorization request
`auth_code_already_used`	400	The authorization code has already been used
`auth_code_expired`	400	The authorization code has expired
`invalid_code_verifier`	400	The PKCE code verifier does not match
`invalid_refresh_token`	400	The refresh token is invalid
`refresh_token_expired`	400	The refresh token has expired
`refresh_token_already_used`	400	The refresh token has already been used
`invalid_client_credentials`	401	Client ID or secret is invalid
`system_error`	500	Internal server error

Tokens Inspect Current Access Token