Access keys (OAuth 2.0)

In the Dashboard, you can:

You can view or create keys with the Developer permission. For edit or delete, you must have the Owner permission.

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:

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.

An Access key consists of 2 parts:

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:

curl --location --request POST 'https://access.sandbox.checkout.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <ACCESS_TOKEN>' \
--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:

{
    "access_token":"<YOUR ACCESS TOKEN>",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"fx gateway vault"
}

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:

Authorization: Bearer <ACCESS_TOKEN>

Step 4: The Resource Server returns a response