API credential management

Your Liquidity Hub API credentials enable you to get a Bearer authentication token from the /oauth/token endpoint. You must use this token to access the Liquidity Hub API's secured endpoints in both production and sandbox environments. You can create, rotate, and delete API credentials in the Liquidity Hub user interface.

Prerequisite

You must have permissions to view and edit API credentials. Check your permissions in your user profile in the Liquidity Hub UI.

API environments

The Liquidity Hub API has two environments: production and sandbox. You must create separate API credentials in the production and sandbox Liquidity Hub UIs to use in the corresponding API environments. Access the production UI at liquidityhub.ripple.com, and the sandbox UI at sandbox.liquidityhub.ripple.com.

Create a new API credential

To create a new API credential:

Select the correct UI environment

If you want API credentials to use in the production API environment, log into the production UI environment. If you want API credentials to use in the sandbox API environment, log into the sandbox UI environment.

  1. Log in to the Liquidity Hub UI .
  2. On the top right corner, click the gear icon to open the Settings dropdown menu.
  3. In the Settings dropdown menu, click API Credentials .
  4. To create a new set of credentials, click New Credential .
  5. The Client ID, Audience, and Client Secret associated with your new API credential are displayed.
Caution

The Client Secret is displayed only when you create the credential. You can't retrieve it after you exit the New credential created dialog. Copy and save your Client Secret in a secure location. If you lose access to the Client Secret, you must rotate this credential or create a new credential.

You can now use the Client ID and Client Secret associated with your API credential to request access tokens using the Liquidity Hub API’s oauth/token/ endpoint.

Secure API credential storage

We recommend storing your client_id and client_secret information in an encrypted properties file.

Access an existing API credential

You can view a list of existing API credentials for a specific environment in the Liquidity Hub UI for that environment.

To view the name and client ID of an existing API credential:

  1. Log in to the Liquidity Hub UI environment of your choice.
  2. In the top right corner, click the gear icon to open the Settings dropdown menu.
  3. In the Settings dropdown menu, click API Credentials . The table lists the name and client ID of all existing API credentials.

Edit an API credential

You can edit an existing API credential for a specific environment to change its name.

To change the name of an API credential:

  1. Log in to the Liquidity Hub UI environment of your choice.
  2. In the top right corner, click the gear icon to open the Settings dropdown menu.
  3. In the Settings dropdown menu, click API Credentials .
  4. In the overflow menu corresponding to the key you want to edit, click Edit .
  5. In the Edit credential name dialog, enter a new name.
  6. Click Save to save the new name.

Rotate an API credential

We recommend rotating API credentials for all environments at regular intervals per your organization's security policy.

To rotate an API credential:

  1. Log in to the Liquidity Hub UI environment of your choice.
  2. In the top right corner, click the gear icon to open the Settings dropdown menu.
  3. In the Settings dropdown menu, click API Credentials .
  4. In the overflow menu corresponding to the key you want to rotate, click Rotate Credential .

The new Client Secret associated with your credential is displayed. Your Client ID and Audience remain the same.

Caution

The Client Secret is displayed only when you rotate the credential. You can't retrieve it after you exit the Credential rotated dialog. Copy and save your Client Secret in a secure location. If you lose access to the Client Secret, you will have to rotate this credential or create a new credential.

Delete an API credential

To delete an API credential:

  1. Log in to the Liquidity Hub UI environment of your choice.
  2. On the top right corner, click the gear icon to open the Settings dropdown menu.
  3. In the Settings dropdown menu, click API Credentials .
  4. In the overflow menu corresponding to the credential you want to delete, click Delete .
  5. In the confirmation dialog, click Delete .