API credentials best practices

Follow these practices to securely use and store your API credentials with Ripple Custody (Wallet). For the procedures to create, disable, and delete credentials, see Manage API credentials.

1. Limit credential permissions: assign each set of credentials the least privilege necessary, following the principle of least privilege (PoLP).
2. Implement IP allowlisting: only allow requests from specified trusted IP addresses, rather than all IP addresses. This prevents access requests from unknown sources. See Configure IP allowlisting.
3. Rotate credentials regularly: delete old credentials and create new ones on a defined schedule (for example, quarterly) to limit the risk of a compromised clientSecret.
4. Store the client secret securely: Ripple Custody (Wallet) displays the client secret only once. Keep it in a secrets manager or secure vault.
5. Separate by environment: use different credentials for sandbox and production. Never share credentials across environments.
6. Monitor credential usage: use audit logging to track which credentials are making API calls and when.
7. Require approval for new credentials: set up an approval group for API credentials to prevent unauthorized creation. See Configure approval flows.
8. Document credential ownership: record which team or service owns each credential and who is responsible for rotating it.
9. Request tokens only from the token endpoint: exchange credentials at /v2/credentials/oauth/token whenever you need a token, and don't build your own token cache. See Use API credentials.

The principle of least privilege (PoLP) refers to creating API credentials with as little privilege, or scope, as possible. This practice limits permissions to only those necessary to complete the task at hand.

When credentials are limited to specific scopes, even if they're compromised, the damage an attacker can inflict is constrained to the permissions assigned to those credentials. The PoLP therefore minimizes the exposure of sensitive operations and data to potential threats.

Using multiple sets of credentials for differing operation types, rather than relying on a single, highly privileged set of credentials, also compartmentalizes access and functionality. This compartmentalization:

• Facilitates auditability: having designated credentials for specific operation types makes it easier to trace and log actions.
• Enhances operational security: multiple credentials let organizations tailor access and permissions to the varied needs and risks of different operation types.

Apply the principle of least privilege to every credential:

• Use the narrowest scope: if a credential only needs access to one vault, set the scope to vault and specify that vault as the resource. Avoid org scope unless the credential genuinely needs organization-wide access.
• Limit actions: grant only the actions the integration needs. A monitoring service needs read only, not create or delete.
• Use one credential per integration: create separate credentials for each service or application. This limits the blast radius if someone compromises a credential.

Applying the principle of least privilege through minimally scoped credentials, and using multiple credential sets for different operations, are vital strategies for enhancing security, managing risk, and maintaining the integrity of the system.

IP allowlisting restricts which network addresses can use a credential. You can configure up to 6 IP entries per credential. Each entry can be a single IPv4 address or a CIDR range.

• Sandbox: use All IP addresses for convenience during development.
• Production: always use Limited IP addresses with the specific IPs or CIDRs of your application servers. Never use All IP addresses in production environments.

You can't change a credential's IP address settings after you create it. To change them, create a new credential and delete the old one.