Request an access token

Request

Request an access token for authentication with Ripple APIs.

You need to request a token for the environment you want to authenticate with.

Note: The length of the access token isn't fixed, hence it can vary. Avoid validating tokens based on character length.

Tutorials

Learn how to Request an access token.

Environments

Environment	Domain	Description
Test	`api.test.ripple.com`	Test environment with simulated currency.
Production	`api.ripple.com`	Production environment for Payments Direct

Security

BasicAuth

Authorizationstring

Optional base64-encoded client_id:client_secret. If provided here they aren't required in the request body.

Example:Basic ZGVtbzpwQDU1dzByZA==

Body

required

client_idstringrequired

The client ID associated with a specific set of API credentials.

Example:"{YOUR_CLIENT_ID}"

client_secretstringrequired

The client secret associated with a specific set of API credentials.

Example:"{YOUR_CLIENT_SECRET}"

audiencestringrequired

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

Format: urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}

The first component is urn:ripplexcurrent-.
The second component refers to the environment you want to access.
The third component is your tenant ID. Ripple integration engineers provide this component during training.

Environment	Environment string	Description
UAT	`uat`	UAT environment with simulated partners and simulated currency.
Production	`prod`	Production environment for Ripple's internal services.

Example: urn:ripplexcurrent-uat:{YOUR_TENANT_ID}

Example:"urn:ripplexcurrent-uat:{YOUR_TENANT_ID}"

grant_typestringrequired

Set the grant-type for this client credentials request. This must be set to client_credentials.

Value:"client_credentials"

Example:"client_credentials"

curl -i -X POST \
  -u '<username>:<password>' \
  https://docs.ripple.com/_mock/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/v2/oauth/token \
  -H 'Authorization: Basic ZGVtbzpwQDU1dzByZA==' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-uat:{YOUR_TENANT_ID}",
    "grant_type": "client_credentials"
  }'

Responses

Returns the authentication response object that includes the token, type, scopes, and expiry.

Bodyapplication/json

access_tokenstring

The bearer token you use when authenticating with a Ripple API.

Example:"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ"

scopestring

List of scopes applied to your access_token.

Example:"pos:payments:create quote_collection:quote:create quote:quote:read pos:payments:read pcs_config:external_read data_requirements:read identities:creat

expires_ininteger, (int64)

How long your access_token is valid. You need to request a new token when it expires.

Example:3600

token_typestring

The type of token. Ripple APIs use Bearer auth tokens.

Example:"Bearer"

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  "scope": "pos:payments:create quote_collection:quote:create quote:quote:read pos:payments:read pcs_config:external_read data_requirements:read identities:create identities:read identities:write ledger:balance:read ledger:read",
  "expires_in": 3600,
  "token_type": "Bearer"
}