# 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 | api.test.ripple.com | Test environment with simulated currency. |
| Production | api.ripple.com | Production environment for Ripple Payments Direct |

Endpoint: POST /v2/oauth/token
Version: 2025.11
Security: BasicAuth

## 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 fields (application/json):

  - `client_id` (string, required)
    The client ID associated with a specific set of API credentials.
    Example: "{YOUR_CLIENT_ID}"

  - `client_secret` (string, required)
    The client secret associated with a specific set of API credentials.
    Example: "{YOUR_CLIENT_SECRET}"

  - `audience` (string, required)
    The value of the audience field is based on [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) 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-test:{YOUR_TENANT_ID}
    Example: "urn:ripplexcurrent-test:{YOUR_TENANT_ID}"

  - `grant_type` (string, required)
    Set the grant-type for this client credentials request. This must be set to client_credentials.
    Enum: "client_credentials"

## Response 200 fields (application/json):

  - `access_token` (string)
    The bearer token you use when authenticating with a Ripple API.
    Example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJ"

  - `scope` (string)
    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:create identities:read identities:write ledger:balance:read ledger:read"

  - `expires_in` (integer)
    How long your access_token is valid. You need to request a new token when it expires.
    Example: 3600

  - `token_type` (string)
    The type of token. Ripple APIs use Bearer auth tokens.
    Example: "Bearer"

## Response 400 fields (application/json):

  - `error_description` (string)
    Summary of the returned problem.
    Example: "Unauthorized"

  - `error` (string)
    Error status.
    Example: "access_denied"

## Response 401 fields (application/json):

  - `error_description` (string)
    Summary of the returned problem.
    Example: "Unauthorized"

  - `error` (string)
    Error status.
    Example: "access_denied"

## Response 403 fields (application/json):

  - `error_description` (string)
    Summary of the returned problem.
    Example: "Unauthorized"

  - `error` (string)
    Error status.
    Example: "access_denied"