Authentication in Ripple Custody uses two layers:
| Layer | Purpose | Used by |
|---|---|---|
| JSON Web Token (JWT) | Identifies the caller for the current session. | UI and API requests. |
| Digital signature | Authorizes a specific state mutation operation and creates an audit trail. | Intent proposals, approvals, and rejections. |
Read-only API requests require a valid JWT. User-signed state mutation requests also require a digital signature over the intent request. In the UI, the Ripple Custody: Auth & Sign app handles key storage, login, and signing. API clients and custom integrations need their own key-generation, JWT, and signing flow.
| Task | Use this page |
|---|---|
| Register, log in, and sign operations in the UI | Register and log in with the UI |
| Generate a signing key pair and share a public key with an administrator | Generate a key pair and register a public key |
| Obtain JWTs, make API requests, and sign intents | Authenticate API requests |
Each user has a public/private key pair.
| Key | Purpose |
|---|---|
| Private key | Kept secret by the user or client. Used to sign authentication challenges and intent requests. |
| Public key | Registered with Ripple Custody. Used to verify signatures from the matching private key. |
Public keys become trusted when they are included in Genesis for initial users, or when a user is created through a governed v0_CreateUser intent after launch. For user governance, see Users and roles.
API authentication uses a challenge-and-signature flow to obtain a JWT:
- Generate a one-time challenge.
- Sign the challenge with the private key.
- Send the public key, challenge, and signature to the authorization server.
- Use the returned JWT as a Bearer token for API requests.
Each challenge can be used only once. For commands and request examples, see Authenticate API requests.
State mutation operations are submitted as intents. The JWT identifies the caller, and the intent signature proves that the caller authorized the exact request. The JWT user and the intent author must identify the same user.
For the intent lifecycle and approval workflow, see Manage intents and approvals. For API signing examples, see Authenticate API requests.