Authenticate API requests

Before authenticating API requests, you must complete:

• Generate keys and register - Your key pair and user account must be set up

You also need:

• Your private key (generated during registration)
• Your public key (in DER format with Base64 encoding)
• The authorization server URL (contact your administrator)
• Your client ID (provided by your administrator)

All API requests require a JWT (JSON Web Token) passed as a Bearer token in the Authorization header. You need to obtain a JWT when you first start using the API and whenever your token expires.

1. You generate a random challenge string.
2. You sign the challenge with your private key.
3. You submit the public key, challenge, and signature to the auth server.
4. The server verifies your signature and issues a JWT.

Create a random string (such as a UUID) and sign it with your private key.

# Create a random challenge (use -n to prevent trailing newline)
echo -n "$(uuidgen)" > challenge.txt

# Sign the challenge
openssl dgst -sha256 -sign privateKey.pem challenge.txt | base64

Submit your credentials to the authorization server:

POST https://openid.{environment_URL}/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=YOUR_CLIENT_ID
&signature=<base64_encoded_signature>
&challenge=<challenge_string>
&public_key=<base64_encoded_public_key>

The server returns a JWT:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 14400
}

The expires_in value is in seconds (14400 = 4 hours).

Include the JWT in the Authorization header of all API requests:

GET /v1/domains
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

All state-changing operations require a digital signature in addition to the JWT. These operations are called "intents" and include:

• Creating entities (users, accounts, domains)
• Updating entities
• Approving or rejecting intents
• Creating transactions

The signature both proves that you explicitly authorized the specific action, and creates an immutable audit trail.

1. Prepare the request object: Build the request object containing author, expiry, target domain, and payload (see Intent request structure below)

2. Canonicalize: Convert the request object to canonical JSON format (see Canonicalization rules below)

3. Sign: Hash the canonical JSON with SHA-256 and sign with your private key

4. Encode the signature: Serialize the signature in DER format with Base64 encoding

5. Add to request body: Include the signature in the signature field of the request body (not a header)

All intents follow this structure. The signature is computed over the canonicalized request object only:

{
  "request": {
    "author": {
      "id": "<your-user-uuid>",
      "domainId": "<your-domain-uuid>"
    },
    "expiryAt": "2026-02-25T12:00:00.000Z",
    "targetDomainId": "<target-domain-uuid>",
    "id": "<new-intent-uuid>",
    "customProperties": {},
    "payload": {
      "type": "v0_CreatePolicy",
      "...": "payload-specific fields"
    },
    "description": "Human-readable description",
    "type": "Propose"
  },
  "signature": "<base64-signature-of-canonicalized-request-object>"
}

Canonical JSON ensures that identical data always produces identical signatures, regardless of how the JSON was originally formatted. The rules are:

Example transformation:

Original JSON:

{
  "type": "v0_CreateTransactionOrder",
  "note": null,
  "details": {
    "amount": "100",
    "asset": "USD"
  }
}

Canonical JSON:

{"details":{"amount":"100","asset":"USD"},"type":"v0_CreateTransactionOrder"}

Use jq to canonicalize the JSON before signing:

cat intent.json | jq -j -S -c > intent_sorted.json

jq flags explained:

• -S — Sort object keys alphabetically
• -c — Compact output (removes whitespace)
• -j — No trailing newline (critical—a newline changes the hash)

# Canonicalize the JSON payload
cat intent.json | jq -j -S -c > intent_sorted.json

# Sign the sorted payload
openssl dgst -sha256 -sign privateKey.pem intent_sorted.json | base64 -b0

This example shows the full flow for submitting a signed intent to create a policy.

1. Create the request object (request.json):

{
  "author": {
    "id": "461dac3d-55c6-4ce8-9ce2-dfb97cfbe279",
    "domainId": "67241e7d-f345-459e-9293-475693c45d85"
  },
  "expiryAt": "2026-02-25T12:00:00.000Z",
  "targetDomainId": "67241e7d-f345-459e-9293-475693c45d85",
  "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "customProperties": {},
  "payload": {
    "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "alias": "Daily Operations Policy",
    "rank": 100,
    "intentTypes": ["v0_CreateTransferOrder"],
    "scope": "Self",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "expression": "true",
      "type": "Expression"
    },
    "workflow": [{"role": "admin", "quorum": 1, "type": "RoleQuorum"}],
    "lock": "Unlocked",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  },
  "description": "Create a policy for daily operations",
  "type": "Propose"
}

2. Canonicalize and sign:

# Canonicalize (sort keys, compact, no trailing newline)
cat request.json | jq -j -S -c > request_canonical.json

# Sign (P-256/secp256k1 on macOS)
SIGNATURE=$(openssl dgst -sha256 -sign privateKey.pem request_canonical.json | base64 | tr -d '\n')

3. Build and submit the full request:

# Build the full request body with signature
REQUEST=$(cat request.json)
cat > intent_body.json << EOF
{
  "request": $REQUEST,
  "signature": "$SIGNATURE"
}
EOF

# Submit to the API
curl -X POST "https://api.example.com/v1/intents" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @intent_body.json

Expected response:

{
  "requestId": "8737c2a2-e8e1-46bf-a2a4-9918437f4a29"
}

Approving an intent uses a different request structure than proposing. For complete details on the approval workflow, see Approve and reject intents.

Example approval request:

{
  "request": {
    "author": {
      "id": "828b554c-c9c9-11eb-a79b-dcfb48cfb3cb",
      "domainId": "455ad43e-cdd9-11eb-8465-dcfb48cfb3cb"
    },
    "targetDomainId": "455ad43e-cdd9-11eb-8465-dcfb48cfb3cb",
    "expiryAt": "2026-02-26T12:00:00.000Z",
    "intentId": "846b5c3c-27e3-4146-ab18-ce6732624d35",
    "proposalSignature": "<signature-from-original-proposal>",
    "approvalReason": "Approved after review",
    "type": "Approve"
  },
  "signature": "<base64-signature-of-canonicalized-request-object>"
}

The proposalSignature is retrieved from the original intent's data.details.proposalSignature field.

The two-layer authentication model enforces:

1. JWT identifies the caller — The server extracts user identity from the JWT token
2. Signature proves authorization — The digital signature proves the author explicitly authorized the action
3. Both must be consistent — The JWT user and the intent author must be the same person

This prevents delegation attacks where a compromised JWT could be used to forge actions for other users.

• Authentication - Conceptual overview of authentication in Ripple Custody
• Generate keys and register - One-time setup for new users
• Approve and reject intents - Complete approval workflow
• Verifying Custody signatures - How to verify signatures on data returned by the platform