Skip to content

Access keys (OAuth 2.0)

Last updated: June 29, 2022

Manage your keys in the Dashboard

From the Developers page in Dashboard, you can:

  • List and view your keys.
  • Create new keys.
  • Edit or delete existing keys.

Any user with Developer or Admin permissions can view or create keys, but only users with the Owner permission are able to edit or delete existing keys.

See our Developers documentation for more information.

Access key configuration

Access keys are used for server-to-server authentication and are supported across most of our endpoints (see our API reference). If you want to use key authentication on an endpoint where it isn't specified in our API reference, please email support@checkout.com.

You can choose how you want your access keys configured:

  • A single key that has access to all of the APIs you want to use.

  • Multiple keys each one with access to a specific set of APIs you will use.

Multiple key use case

For example, you might have separate systems for processing payments and managing disputes. Each one has different security requirements, and you don't want the disputes management system to have access to any sensitive information about payment processing. To keep them separate, you could have one secret key to access our Unified Payment API for payment processing, and a second secret key that only has access to our Disputes API for disputes management.

Using your access key

An access key consists of 2 parts:

  • The access key identifier (this corresponds to the OAuth 2.0 client ID)
  • The access key secret (this corresponds to the OAuth 2.0 client secret)

The Client Credentials flow is for server-to-server authentication and has the following steps:

Step 1: The Application requests an access token

Your application needs an access key ID and secret in order to authenticate. You need to set it up to make a request to the POST /connect/token endpoint, with the Basic prefix in the Authorization header. For example:

1
2
3
4
curl --location --request POST 'https://access.sandbox.checkout.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic base64(<access_key_id>:<access_key_secret>)' \
--data-urlencode 'grant_type=client_credentials' \

You can optionally provide one or more scopes to indicate the resources it requires access to as a part of this request. If you don't provide it, the default scopes assigned when the credential were created will apply. Any explicitly provided scopes must be a subset of the scopes assigned when the access key is created.

Step 2: The Authorization Server validates the Client Credentials authentication

The Authorization Server also validates access to the requested scopes. If the request is valid, an access token is returned.

For example:

1
2
3
4
5
6
{
"access_token":"<YOUR ACCESS TOKEN>",
"expires_in":3600,
"token_type":"Bearer",
"scope":"fx gateway vault"
}

Access tokens expire after 60 minutes.

The access token is a JSON Web Token (JWT), a special format that allows the secure exchange of information between 2 parties. On expiry, the token will no longer work and the Application must request another token to continue access to the Resource Server. The expiry time of the JWT token will be included in the response.

Step 3: The Application makes a request to the API

The Application uses the previously obtained access token.

Per RFC6750, whenever you use the token, you should include it inside the Authorization header with the Bearer prefix, as follows:

1
Authorization: Bearer <ACCESS_TOKEN>

Step 4: The Resource Server returns a response