You're viewing documentation for our latest API. This will not impact your integration, but you will need the documentation relevant to you. If you have an account with Checkout.com you have received an email confirming which version to use.
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 [email protected].
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.
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 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:
curl --location --request POST 'https://access.sandbox.checkout.com/connect/token' \
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.
"access_token":"<YOUR ACCESS TOKEN>",
"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: