OAuth 2.0 client credentials
Last updated: November 13, 2024
Sign in to the Dashboard.
Select the Developers icon in the top navigation bar and open the Keys tab. From here, 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 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:
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:
Information
Access tokens expire after four hours. We recommend you cache and reuse valid tokens across multiple requests within this timeframe.
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:
Step 4: The Resource Server returns a response