Authentication

To make a payment using any of the Ripple Payments API operations, you need a valid access token.

This access token is required by all Ripple Payments API operations (except the Authentication operation itself). You must include a valid access token in the Authorization header of each request.

Ripple Payments provides a secure model for authentication and authorization by providing access tokens scoped for a set of credentials.

The Authentication operation returns an access token in the access_token response field. You must include your client_id and client_secret in the JSON body to get a valid access token.

Generate client ID and client secret

You need your client ID and client secret to obtain an access token.

If you don't already have your client ID and client secret, do the following:

1. Log in to Ripple Payments .
2. On the top right of the page, click the Settings gear icon.
3. Under Integration , select API Credentials .
4. On the top right of the page, select the access environment from the dropdown list. For example, to provision credentials for the Test environment, select Test from the dropdown list.
5. In the upper right corner of the page, click New Credential .
6. In the Credential name field, enter a name for the credential.
7. Click Save & Generate Key .

You can now use the client ID and client secret to generate access tokens using the authentication operation.

We recommend rotating your API credentials at regular intervals in accordance with your organization's security policy.

Fetch an access token

Once you have your client ID and client secret, follow these steps to obtain an access token that you can use with Ripple Payments API calls:

Determine the desired environment

The first step to fetching an access token it to determine the environment that you want to access.

The following table describes the differences in types of partners and currency for the environments that provide Ripple Payments API access. Take note of the environment string for the environment you want to access.

Request the access token

The request format for an authentication request is as follows:

POST https://api.ripple.com/v2/oauth/token
Content-Type: application/json
{
   "grant_type":"client_credentials",
   "client_id":"{YOUR_CLIENT_ID}",
   "client_secret":"{YOUR_CLIENT_SECRET}",
   "audience": "urn:ripplexcurrent-{ENVIRONMENT_STRING}:{YOUR_TENANT_ID}"
}

The expected values are as follows:

Examples:

Request Example (Production Environment Success) – A successful request to a production environment may look similar to the following example:

POST https://api.ripple.com/v2/oauth/token
Content-Type: application/json
{
    "grant_type": "client_credentials",
    "client_id": "{YOUR_CLIENT_ID}",
    "client_secret": "{YOUR_CLIENT_SECRET}",
    "audience": "urn:ripplexcurrent-prod:{YOUR_TENANT_ID}"
}

Response Example (Production Environment Success) – A successful request returns a response similar to the following example:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "keys:read keys:write payments:create quotes:create identities:create audit:read"
}

Test the access token

Use the /oauth/token/test endpoint to verify the validity of your access token for a specific Ripple environment and determine the remaining time before it expires.

Example token test

This example demonstrates how to use the /oauth/token/test endpoint to test an access token.

Here, we apply the access token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ to the Authorization: Bearer header.

GET https://api.ripple.com/v2/oauth/token/test
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ

Example token test response

The response is a JSON object with the following properties:

• message : Indicates the status of the access token.
• seconds_to_expiry : Represents the number of seconds remaining until the access token expires.

{
"message": "token_ok",
"seconds_to_expiry": 3600
}

Authorize Ripple Payments API operations using the access token

Ripple Payments uses Bearer Token Authorization for all operations (except the Authentication operation itself). To make successful Ripple Payments API requests, include a valid access token in the Authorization header of each request in the following format:

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ

To use this in an in an API request, add the value of the access_token field to the Authorization header for all Ripple Payments API operations (except the Authentication operation itself). Remember to add Bearer (including a space) before the access token.

For example:

GET https://api.ripple.com/v2/payments/{YOUR_PAYMENT_ID}
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ

Access token expiration and caching

Access tokens are valid for 1 hour. After you get a new token, it is cached for a limited amount of time. To avoid problems caused by double caching, don't cache the token client-side. If you do cache the token, you must clear the cache within the time period specified by the expires_in field (as specified by the exp claim in the JWT) in the response body.