To interact with the Ripple Custody (Wallet) API, you need API credentials, which you create and manage in the console.
API credentials are unique secrets that authenticate and authorize access to resources and actions in the system.
You can grant each credential permissions to access specific resources and perform deliberate actions. It gives you fine-grained control over who can interact with the API and what each credential can do.
When you create a credential, Ripple Custody (Wallet) generates a clientId and clientSecret. These act as a username and password: you exchange them for a time-limited Bearer access token using the OAuth 2.0 client credentials flow, which is the only supported flow. The access token authenticates your API requests. When it expires, exchange the credentials again for a new token.
Access tokens last 60 seconds in Production and 1 hour in Sandbox and Development. For the exchange procedure, see Use API credentials.
Each credential is scoped with a permission set that defines exactly what it can do. Each permission has four components:
| Component | Description |
|---|---|
| Type | The resource category (for example, balances, key, vault) |
| Action | The operation (create, delete, read, update) |
| Scope | How broadly the permission applies (org, vault, key, or counterparty for address book entries) |
| Resource | A specific vault or wallet (optional; leave it blank for all resources in the scope) |
Each API credential has a type (the permission set type in the console) that scopes it to a category of API resources and actions. A credential can't call endpoints outside its type: the request returns 403 with reason PAL000.002. Create a separate credential for each category your integration uses.
| Type | Grants access to |
|---|---|
| WALLETS | Vaults, wallets (including vault and wallet tags), and balances |
| TRANSACTIONS | Creating and managing transactions — transfers, raw signing, XRP Ledger transaction types, fee estimation, freezing and unfreezing — and triggering sweeps |
| CONTROLS | Counterparties, address book entries, and policy rules |
| MONITORING | Webhooks and webhook subscriptions |
For example, an integration that reads balances and creates transfers needs two credentials: one of type WALLETS and one of type TRANSACTIONS.
The Create credentials form labels the fourth type Monitoring, but the credentials list shows it as Audit, and API responses return its category as AUDIT. They're the same credential type.
Not everything is available through API credentials. Administrative and security-sensitive domains — devices, MPC quorums, users and roles, approvals, organization settings, API credential management, WalletConnect connections, and sweep configuration — are managed in the Ripple Custody (Wallet) console and authenticated by your console session. API credentials can trigger a configured sweep, but creating or changing sweep configurations happens in the console.