# 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.

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

## 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](https://home.ripple.com).
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 UAT environment, select **UAT** 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**.


Warning
The *client secret* is displayed only once when you are creating new credentials.

You can't 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 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.

| **Environment** | **Request URL** | **Environment String** | **Partners** | **Currency** |
|  --- | --- | --- | --- | --- |
| **UAT** | `https://api.test.ripple.com/v2/oauth/token` | `uat` | Simulated | Simulated |
| **Production** | `https://api.ripple.com/v2/oauth/token` | `prod` | Actual | Actual |


### Request the access token

The request format for an authentication request is as follows:


```json
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:

| **Key** | **Value** | **Description** |
|  --- | --- | --- |
| `grant_type` | `client_credentials` | Set the grant-type for this client credentials request. |
| `client_id` | *{YOUR_CLIENT_ID}* | Log into Ripple Payments UI to retrieve your client ID for Ripple Payments. |
| `client_secret` | *{YOUR_CLIENT_SECRET}* | Retrieve the client secret for Ripple Payments that was generated when you created the current set of credentials in Ripple Payments UI. |
| `audience` | `urn:ripplexcurrent- `*{ENVIRONMENT_STRING}*`:`*{YOUR_TENANT_ID}* | The value of the `audience` field is based on [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) syntax. The second component of the URN must refer to the environment which you want to access. Ripple integration engineers provide you your tenant ID (the third component of the URN) during training. |


Examples:

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


```json
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:


```json
{
    "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.


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

Caution : Access tokens are confidential
Remember to replace the example token `eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ` with your actual access token, and never share your access token publicly.

#### 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.



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

## Authorize Ripple Payments API operations using the access token

Ripple Payments uses [Bearer Token Authorization](https://tools.ietf.org/html/rfc6750) 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:


```json
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:


```json
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.