Generate keys and register

Executive summary

Every user needs a cryptographic key pair. This one-time setup generates your keys and registers your public key with the platform.

Generate a key pair using a cryptographically secure method (P-256, secp256k1, or Ed25519).
Keep your private key secret. Share only the public key with your administrator.
Your public key is registered via governance intent (or genesis block for initial users).
Production keys should be generated and stored in a secure KMS, not manually.

Why this matters

Your key pair is your digital identity on the platform. The private key proves you authorized every action you take — losing it means losing access, and exposing it means someone else can act as you. There is no "forgot password" recovery — key management is the user's responsibility.

For architects and operators: Establish key generation procedures and secure storage guidance for your users. Consider mandating hardware security keys (YubiKey) or the mobile app's secure enclave for production users rather than software-based key storage.

This guide is for regular users who need to register after the platform is running. Genesis users are pre-configured during platform initialization — see Genesis block for details.

Prerequisites

Before you begin, ensure you have:

Access to a cryptographically secure environment for key generation
Contact information for your user administrator
Knowledge of which key type your environment requires (ask your administrator if unsure)

Supported key types

Ripple Custody supports three types of cryptographic keys:

Key type	Curve	Common use	When to choose
P-256 (secp256r1)	NIST P-256	General purpose, widely supported	Default choice for most deployments
secp256k1	Koblitz curve	Bitcoin, Ethereum ecosystems	When integrating with Bitcoin/Ethereum infrastructure
Ed25519	Edwards curve	High performance, modern systems	When performance is critical

All keys must be in DER format with Base64 encoding (without PEM headers/footers).

Ask your administrator which key type is required for your environment before generating keys. Using the wrong key type will cause authentication failures.

Step 1: Generate a key pair

Generate a key pair using a cryptographically secure method. The private key must be kept secret; the public key will be shared with your administrator.

Production environments: Always generate and store production keys using a cryptographically secure key management system (KMS). The OpenSSL examples below are for testing and development only.

OpenSSL examples (non-production)

# Generate private key
openssl ecparam -genkey -name secp256r1 -noout -out privateKey.pem

# Export public key in DER format with Base64 encoding
openssl ec -in privateKey.pem -pubout -outform DER | openssl base64 -A -out publicKey.pem

View your keys

To view the private key (keep this secret):

cat privateKey.pem

Example output:

To view the public key (this is what you share):

cat publicKey.pem

Example output:

MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEg36xU2KQ6xLPCvZ3JXZYf5pFCagAb7WGMlYCN92zzgi737EOkDOCMlZB0TY8CbzRHhG4RUdKuLkdRtD+OVIu2w==

Step 2: Register with your administrator

Send your public key to your user administrator through a secure channel. Never share your private key.

Your administrator will:

Create a v0_CreateUser intent with your public key
Submit the intent for governance approval (based on configured policies)
Notify you once your account is active

Step 3: Verify your registration

After your administrator confirms your account is active, verify your registration by calling the Get user details API operation.

Obtain a JWT token. See Authenticate API requests for the complete JWT flow.
Call the Get current user endpoint with your JWT:

GET /v1/users/current
Authorization: Bearer <your_jwt_token>

Verify the response contains your user ID, public key, and domain memberships:

{
  "id": "user_abc123",
  "domains": ["domain_xyz789"],
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."
}

If you receive a successful response, your registration is complete.

Troubleshooting

Problem	Cause	Resolution
Key generation fails	OpenSSL not installed or outdated	Install or update OpenSSL
Public key rejected by administrator	Wrong key type or format	Verify key type matches environment requirements; ensure DER format with Base64 encoding
Registration not completing	Intent awaiting approval	Contact your administrator to check approval status
Cannot authenticate after registration	Account not yet active	Wait for administrator confirmation; check intent status

Next steps

Once registered, proceed to Authenticate API requests to learn how to obtain JWT tokens and sign intents for ongoing API usage.