# **API Authentication Flow Explained**

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.