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
Name | Nullable | Type | Description |
---|---|---|---|
id | string 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 This field is only available when an access token is first created. It will contain a value of |
account_id | string in EID format in UUID format | ID of the account which the access token belongs to. | |
api_key_id | string in EID format in UUID format | The ID of the API key which this access token is associated with. | |
created_at | string of date/time formatted as RFC 3339 in EID format in UUID format | The time at which the access token was created. | |
expires_at | string 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_type | enum string | The type of token returned. Currently always Enum | |
expires_in | integer | 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 |
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
Name | Required | Type | Description |
---|---|---|---|
client_secret | string | The secret of the requesting client application. Usually obtained under the API keys section of account settings in the Bridge Dashboard. | |
client_id | string 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 This field is optional if you have a newer style API key that has a secret prefixed with | |
expires_at | string 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_in | string | 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 Specified as a number followed by a unit of | |
grant_type | enum string | The grant type which the client application is using to acquire a new access token. Only a value of Enum |
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.