Bearer Token

Bearer Token

Get the Bearer Token

The AUTHORIZATION_CODE may be exchanged for bearer tokens using the token endpoint at https://app.checkbook.io/web/v1/auth/oauth/token

🚧

Sandbox OAuth

If you would like to test the OAuth flow in Sandbox, you will need to use this endpoint to retrieve the bearer token:
https://sandbox.app.checkbook.io/web/v1/auth/oauth/token

❗️

Update Reminder

The old token URL https://checkbook.io/oauth/token will be discontinued after August 1st, 2021. Please update your implementation to use the new URL https://app.checkbook.io/web/v1/auth/oauth/token

This URL accepts a POST request with the parameters:

Request parameterDescription
client_idYour client ID found in Developer Keys
grant_typeauthorization_code
scopeOne of the following values:
  • check: the token can be used multiple times to send or request checks
  • check_receive: the token can be used multiple times to request checks
  • single-use: the token can be used only once to send or request checks
    |
    | code | The AUTHORIZATION_CODE returned in the previous step from the redirect to the callback URI http://REDIRECT_URI?code=AUTHORIZATION_CODE
    |
    | redirect_uri | Your callback URL found in Developer Keys |
    | client_secret | Your secret key found in Developer Keys |

A successful request will return a JSON object with an access_token along with additional information:

FieldDescription
access_tokenYour client ID found in Developer Keys
token_typeBearer
refresh_tokenREFRESH_TOKEN: Token that can be used to refresh the Bearer Token
scopeThe same scope that was used in the request

Request

Here is an example of a request:

curl --request POST \
  --url https://demo.checkbook.io/web/v1/auth/oauth/token \
  --header 'application/x-www-form-urlencoded' \
  --data 'client_id=313910200b834c009f62ae47feeee407&grant_type=authorization_code&scope=check&code=8hXMj1T9D36qL2uzb19s5OaNnkT6Vq&redirect_uri=https://example.com&checkbook_oauth_redirect&client_secret=dXbCgzYBMibj8ZwuQMd2NXr6rtvjZ8'

Response

Here is an example of the corresponding response:

{
  "access_token": "Nv6XB8OQ3IfT77Y9IknZqe87bFiF6Z", 
  "token_type": "Bearer", 
  "expires_in": 15552000, 
  "refresh_token": "v0sRbFofMnKB2GmMyGnoOsot1VbpDU", 
  "scope": "check"
}

📘

Note

The previous request is for the demo environment and cannot be used for an actual OAuth implementation. You will need to use either the sandbox or the production authorization endpoint.

Refresh the Bearer Token

When the BEARER_TOKEN expires, you need to make another request to the endpoint at https://app.checkbook.io/web/v1/auth/oauth/token to receive a new token.

🚧

Sandbox OAuth

If you would like to test the OAuth flow in Sandbox, use this endpoint to get the bearer token: https://sandbox.app.checkbook.io/web/v1/auth/oauth/token

This URL accepts a POST request with the parameters:

Request parameterDescription
client_idYour client ID found in Developer Keys
grant_typerefresh_token
refresh_tokenThe REFRESH_TOKEN returned in the previous step
client_secretYour secret found in Developer Keys

A successful request will return the JSON object with an access_token; the same as the initial response for getting the Bearer token.

Request

Here is an example of a request:

curl --request POST \
  --url https://demo.checkbook.io/web/v1/auth/oauth/token \
  --header 'application/x-www-form-urlencoded' \
  --data 'client_id=313910200b834c009f62ae47feeee407&grant_type=refresh_token&refresh_token=v0sRbFofMnKB2GmMyGnoOsot1VbpDU'

📘

Note

The previous request is for the demo environment and cannot be used for an actual OAuth implementation. You will need to use either the sandbox or the production authorization endpoint.

Make API Calls

The BEARER_TOKEN (i.e. the access_token from the JSON response) will be used for authentication when making API requests, instead of the normal authorization header :

Authorization: bearer BEARER_TOKEN

So for the previous example, the authorization header would need to look like this:

Authorization: bearer Nv6XB8OQ3IfT77Y9IknZqe87bFiF6Z