Request an access token

Access tokens are used in token-based authentication to grant applications access to APIs on behalf of a user. After a user successfully logs in and authorizes access, the application receives an access token. This token acts as a credential that the application uses to identify itself and the authorized user when calling the target API.

You must include a valid access token in your request header when you send requests to secured API endpoints.

To get an access token, you must have your client ID and client secret. Learn how to generate a client ID and client secret in the Payments Direct API reference.

To get an authentication token for the UAT environment, send a POST request to the following URL:

https://api.test.ripple.com/v2/oauth/token

To get an access token, use the authenticate operation in the Payments Direct API reference.

Include the audience and grant_type as shown in the example below.

The value of the audience field is based on URN syntax.

Format: urn:ripplexcurrent-ENVIRONMENT_STRING:YOUR_TENANT_ID

Example: urn:ripplexcurrent-uat:YOUR_TENANT_ID

curl -X POST 'https://api.test.ripple.com/v2/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-uat:{YOUR_TENANT_ID}",
    "grant_type": "client_credentials"
  }'

Store the access_token for use with all other API operations.

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  "scope": "identities:create identities:read identities:write quote_collections:write payments:accept payments:read",
  "expires_in": 3600,
  "token_type": "Bearer"
}

If a token request is rejected, the response body contains an error and an error_description. A 403 with error: unauthorized_client means the client is not authorized to request a token; a 403 with error: access_denied means the service is not enabled for the requested domain. Handle these based on the HTTP status code rather than the error string, and do not retry a 403 with the same request. For the full list of authentication responses, see the Payments Direct API reference.