# Authentication

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.

## Choose your path

| Task | Use this page |
|  --- | --- |
| Register, log in, and sign operations in the UI | [Register and log in with the UI](/products/custody/identity-and-access/authentication/ui-authentication) |
| Generate a signing key pair and share a public key with an administrator | [Generate a key pair and register a public key](/products/custody/identity-and-access/authentication/generate-api-keys-and-register) |
| Obtain JWTs, make API requests, and sign intents | [Authenticate API requests](/products/custody/identity-and-access/authentication/authenticate-api-requests) |


## Key model

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](/products/custody/governance/users).

## API authentication flow

API authentication uses a challenge-and-signature flow to obtain a JWT:

1. Generate a one-time challenge.
2. Sign the challenge with the private key.
3. Send the public key, challenge, and signature to the authorization server.
4. 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](/products/custody/identity-and-access/authentication/authenticate-api-requests).

## Intent signing

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](/products/custody/governance/intents/manage-intents-and-approvals). For API signing examples, see [Authenticate API requests](/products/custody/identity-and-access/authentication/authenticate-api-requests#signing-intents-state-mutation-operations).

## Related topics

- [Users and roles](/products/custody/governance/users)
- [Genesis](/products/custody/governance/genesis)
- [Security model](/products/custody/overview/security-model)
- [Verifying Custody signatures](/products/custody/overview/security/data-integrity-and-audit-trail#verifying-custody-signatures)