Skip to content

This discussion provides a detailed technical explanation of the authentication flow required to use the Ripple Custody API, which is a key part of the "Getting Started" process for developers.

Here is a summary of the concepts explained:

Asymmetric Cryptography

The entire authentication system is built on public/private key cryptography (specifically Elliptic Curve Cryptography).

  • Private Key: A secret key that the user possesses and never shares. Its only purpose is to sign data.
  • Public Key: A key that is shared publicly. Its purpose is to verify a signature created by the corresponding private key.

The Authentication Flow

The process of proving your identity to the API involves several steps:

  1. Genesis: First, the system must be initialized with a Genesis block. This configuration must include the public key of the initial admin user. This tells the system to "trust" this public key.
  2. Get challenge: The user (or their custom application) generates a "challenge," which is just a block of random data (e.g., 64 bytes).
  3. Sign challenge: The user uses their private key to create a cryptographic signature of that challenge.
  4. Authenticate: The user sends their public key, the original challenge, and the signature to the authentication endpoint.
  5. Verification: The server performs two checks:
    • It uses the provided public key to verify that the signature is valid for the challenge.
    • It checks if that public key is in its list of trusted keys (from the Genesis block).
  6. Get token: If both checks pass, the server has proof that the user owns the private key. It then issues a JSON Web Token (JWT).
  7. Make API calls: This JWT (not the private key or signature) is then used as a Bearer token in the authorization header for all subsequent API calls to the platform.

Key Types (A Source of Complexity)

The speaker notes that the platform supports three different types of cryptographic keys (P-256/R1, secp256k1/K1, and ED25519). This is a key technical detail as developers must ensure they are using the correct type.

Client Applications

This same authentication flow is used by all clients:

  • Ripple's Web App & Mobile App: They perform this challenge-and-signature flow internally.
  • Custom Client Backends: A client building a custom application (like a trading desk) would use this same flow (with a machine-to-machine grant type) to authenticate their own backend service.