Access token

Access tokens are short-lived secrets used to authenticate with the API. They're procured using long-lived API keys which are created via the Crunchy Dashboard.

Using access tokens isn't necessary for API authentication (an API key can be used instead), but they can be useful for security-critical situations to reduce the exposure of a long-lived secret. So for example, a program makes all API requests with access tokens, and in case one of those access tokens is leaked in transport or gets accidentally persisted to some logs, since it expires quite quickly, it's far less likely for an attacker who recovers it to be able to use it for anything. And since an access token cannot be used to procure a new access token, even if they were able to recover a live access token, its use has a hard time bound on it.

Access tokens expire after one hour by default, and can be made to expire up to one week from now by specifying a time in expires_at or a duration in expires_in.

For full details and examples on this exchange process, see authentication.

Part of the API reference collection

This page is part of the Crunchy Bridge API reference, and primarily meant to act as an exhaustive guide for technical integrations which are already in progress. To understand the basics of using the API, see API concepts and getting started.

The AccessToken API resource

Access token response.

Content type: application/json

NameNullableTypeDescription
idstring in EID format in UUID format

The primary ID of the access token.

access_token✔string

The access token secret. This will be passed into the Authorization header when making subsequent API requests.

This field is only available when an access token is first created. It will contain a value of null when this API resource is returned from other endpoints.

account_idstring in EID format in UUID format

ID of the account which the access token belongs to.

api_key_idstring in EID format in UUID format

The ID of the API key which this access token is associated with.

created_atstring of date/time formatted as RFC 3339 in EID format in UUID format

The time at which the access token was created.

expires_atstring of date/time formatted as RFC 3339 in EID format in UUID format

The time at which the access token expires, after which a new access token will need to be procured.

token_typeenum string

The type of token returned. Currently always bearer.

Enum bearer.

expires_ininteger

The number of seconds until the access token expires, after which a new access token will need to be procured.

Deprecated It's generally preferable to use expires_at instead for simplicity's sake.

Example

{
    "access_token": "cbats_H4sIAAAAAAAA_2TKTW6EIBQA4Lu8tSaKqAnn6Kob84Cngog_iFWa3r2Zmcxq9t8vGA0CcMDkZQitmpdU_1ivtwFJx3aGDHA13UR395ReqhBHl3RNZneqrmI1JnvdPX9IpZboj5eknjvpNpxOQmflfVrp-sTOiJCB2gkP0h0eIIAVjOVFkzP-VTaCVaLk35ABXavZKXya9m3-_gMAAP__2N6M378AAAA.MEUCIATMeSR2YnPuF-JaEjzeqBe0uj7461hpNfDzzyYR8_c3AiEAqaqypU-PsFt7camAjlBpHEGV32zOAJ_Xm4N128nNsqo",
    "account_id": "qvcw4hylovgyzbwzp53bmmlhga",
    "api_key_id": "ryexlkxpibfang6u7374faajfe",
    "created_at": "2021-07-11T01:02:03Z",
    "expires_at": "2021-07-11T02:02:03Z",
    "expires_in": 3600,
    "id": "rizcplozgfht7lhra5lbqebiru",
    "token_type": "bearer"
}

Create access token

Create a new access token.

Historically, it was necessary to pass both client_id and client_secret fields in to create an access token. These are both still accepted, but now only client_secret is strictly required.

The access_token field in the response contains the access token secret which can then be passed into other API requests as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer cbats_H4sIAAAAAAAA_2TKTW6EIBQA4Lu8tSaKqAnn6Kob84Cngog_iFWa3r2Zmcxq9t8vGA0CcMDkZQitmpdU_1ivtwFJx3aGDHA13UR395ReqhBHl3RNZneqrmI1JnvdPX9IpZboj5eknjvpNpxOQmflfVrp-sTOiJCB2gkP0h0eIIAVjOVFkzP-VTaCVaLk35ABXavZKXya9m3-_gMAAP__2N6M378AAAA.MEUCIATMeSR2YnPuF-JaEjzeqBe0uj7461hpNfDzzyYR8_c3AiEAqaqypU-PsFt7camAjlBpHEGV32zOAJ_Xm4N128nNsqo"

We recommend that access tokens be reused between requests as much as possible before they expire. This makes programs more efficient because you don't end up with two separate API calls for every operation (i.e. one to procure an access token and the other for the operation).

POST /access-tokens

Request body schema

Content type: application/json

NameRequiredTypeDescription
client_secretstring

The secret of the requesting client application. Usually obtained under the API keys section of account settings in the Bridge Dashboard.

client_idstring in EID format in UUID format

The ID of the requesting client application. Usually obtained under the API keys section of account settings in the Bridge Dashboard. Equivalent to the application_id field from an API key response.

This field is optional if you have a newer style API key that has a secret prefixed with cbkey_. In that case, you only have to provide client_secret to this endpoint.

expires_atstring of date/time formatted as RFC 3339 in EID format in UUID format

A target time for the access token to expire between one minute and one month from now. If omitted, the access token doesn't expire. Use only one of expires_at or expires_in.

expires_instring

A target duration for the access token to expire between one minute and one month from now. If omitted, the access token doesn't expire. Use only one of expires_at or expires_in.

Specified as a number followed by a unit of s (second), m (minute), h (hour), d (day), w (week), or M (month), like 15m (15 minutes) or 30d (30 days).

grant_typeenum string

The grant type which the client application is using to acquire a new access token. Only a value of client_credentials is supported. This field may be omitted to use the default value of client_credentials.

Enum client_credentials.

Example request body

{
    "client_id": null,
    "client_secret": "cbkey_IT_qM9o80pwp-dIPPRbQ8yql_BIrZznI4zobc7HIGUg",
    "expires_at": null,
    "expires_in": "1w",
    "grant_type": ""
}

cURL example

curl -X POST https://api.crunchybridge.com/access-tokens
    -H "Authorization: Bearer $CRUNCHY_API_KEY"
    -H "Content-Type: application/json"
    -d '{"client_id":null,"client_secret":"cbkey_IT_qM9o80pwp-dIPPRbQ8yql_BIrZznI4zobc7HIGUg","expires_at":null,"expires_in":"1w","grant_type":""}'

Response

Status: 200

Responds with the standard AccessToken API resource.

Destroy access token

Delete an existing access token.

DELETE /access-tokens/{access_token_id}

Request

Path parameters

  • access_token_id: The primary ID of the access token to delete. Must belong to your account.

cURL example

curl -X DELETE https://api.crunchybridge.com/access-tokens/{access_token_id}
    -H "Authorization: Bearer $CRUNCHY_API_KEY"

Response

Status: 200

Responds with the standard AccessToken API resource.