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.

Prerequisites

To obtain an access token, you need your API client ID and client secret that you created using the Ripple Payments UI.

If you don't already have your client ID and client secret, see Settings > API credentials in the Payments ODL UI section on how to generate a client ID and client secret.

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 RippleNet Cloud 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://auth.rnc.ripplenet.com/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://auth.rnc.ripplenet.com/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:read payments:config quotes:read quote_collections:return quote_collections:write payments:accept payments:lock payments:reject payments:settle payments:finalize payments:fail payments:label payments:node_status payments:complete fxrates:read fxrates:write fee:read fee:write accounts:read accounts:write monitor:balances transfers:read transfers:label transfers:write user:read quote_collections:read exchange_transfers:write exchange_transfers_quote:write exchange_transfers:read exchange_transfers_complete:write account_liquidity:config request_for_payment:write request_for_payment:accept request_for_payment:fail request_for_payment:read user:write xvia:write"
}

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://sf-bank.ripplenet.com/v1/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.

IP allowlisting

The Authentication operation is protected by the Ripple Payments allowlist. If you have already allowlisted your middleware IP to access the Ripple Payments API, you don't need to take any further action. For instructions on adding your middleware IP to the Ripple Payments allowlist, see IP allowlisting.