Authentication API

Download OpenAPI specification:Download

The Authentication API allows you to generate access tokens to authenticate with Ripple APIs.

All API operations require an access token specific to the environment you're using. Ripple 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 request body to get a valid access token.

Generate client ID and client secret

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

If you do not already have your client ID and client secret, do the following:

  1. Log into Ripple Payments UI.
  2. In the left navigation menu, click Settings.
  3. Under Administration, click API Credentials.
  4. In the dropdown list next to the page title, select the access environment. 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. Click Save and Generate Key.

Caution: The client secret is displayed only once when you are creating new credentials. You cannot retrieve the secret after exiting this page. Copy and store the client secret securely and share it with authorized individuals in accordance with your organization's security policy.

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 according to your organization's security policy.

Fetch an access token

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

Step 1: Determine the desired environment

The first step to request an access token is to determine the environment where you want to use the API.

The following table describes the different environments that provide Ripple Payments Direct API access. Take note of the environment string for the environment you want to access.

Environment Request URL Environment String Currency
Test https://auth-test.rnc.ripplenet.com/oauth/token test Simulated
Production https://auth.rnc.ripplenet.com/oauth/token prod Actual

Step 2: Request the Access Token

Step 3: Test the Access Token

Authentication

Request an access token

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.

Environments

Environment Domain Description
Test auth-test.rnc.ripplenet.com Test environment with simulated partners and simulated currency.
Production auth.rnc.ripplenet.com Production environment for Ripple's internal services.
SecurityBasicAuth
Request
header Parameters
Authorization
string

Optional base64-encoded client_id:client_secret.

If provided here they aren't required in the request body.

Example: Basic ZGVtbzpwQDU1dzByZA==
Request Body schema:
required
client_id
required
string

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

See API authentication for instructions obtaining your client ID.

client_secret
required
string

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

See API authentication for instructions obtaining your client secret.

audience
required
string

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

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

  • The first component is urn:ripplenetxcurrent-.
  • 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
Test test Test environment with simulated partners and simulated currency.
Production prod Production environment for Ripple's internal services.

Example: urn:ripplexcurrent-prod:{YOUR_TENANT_ID}

grant_type
required
string

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

Value: "client_credentials"
Responses
200

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

Response Schema: application/json
access_token
string

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

scope
string

List of scopes applied to your access_token.

expires_in
integer <int64>

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

token_type
string

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

400

Bad Request

401

Unauthorized

403

Forbidden

post/oauth/token
Request samples
{
  • "client_id": "{YOUR_CLIENT_ID}",
  • "client_secret": "{YOUR_CLIENT_SECRET}",
  • "audience": "urn:ripplexcurrent-prod:{YOUR_TENANT_ID}",
  • "grant_type": "client_credentials"
}
Response samples
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ",
  • "scope": "identities:create identities:read identities:write quote_collections:write payments:accept payments:read routing_table:lookup",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}

Test access token

Test if an access token can be used for authentication with Ripple APIs and how much time remains on it.

SecurityBearer
Responses
200

If a valid access token is supplied, the time remaining before the token expires is returned.

Response Schema: application/json
Array
message
string

Success message

seconds_to_expiry
integer <int64>

Remaining time in seconds before the tested token expires.

400

Bad Request

401

Unauthorized

get/oauth/token/test
Request samples 
Response samples 
application/json
[
  • {
    • "message": "token_ok",
    • "seconds_to_expiry": 3600
    }
]