Skip to main content

Overview - Add User API Key

API Key & Request Signing: Authentication Flow​

Every request sent to the XD Ledger must be digitally signed by the actual sender of the request. This ensures request integrity and security. Below are the authentication and key management approaches supported by the XD Ledger.

Standard Flow – Direct Integration​

For direct API integration:

  • Each end user (or system user) must possess:
    • An API Key
    • A Key ID
    • A Private Key

These credentials are required to digitally sign requests sent to XD Ledger.

Alternate Flow – Middleware Involvement​

In cases where a Middleware Application is used to manage user authorization and lifecycle:

  • The middleware obtains its own API Key & Key ID from XD Ledger.
  • The middleware is responsible for:
    • Creating end customers
    • Creating customer accounts

For any money movement (transactional) requests, the end customer must still sign requests using their own keys.

Customer Key Registration – Two Approaches​

Approach 1: Middleware Registers End Customer Key (No Email Validation)​

This approach allows onboarding without validating the customer's email via OTP.

  1. Mobile App (Client-Side):

    • Generates a key pair (Public Key & Private Key).
    • The Private Key is securely stored in the mobile app.

  2. Middleware:

    • Calls the addUserKey API with:
      • The email address of the end customer (used as the username).
      • The Public Key generated from the mobile app.
    • Signs the request using its own API credentials.
  1. XD Ledger:
    • Responds with:
      • An API Key
      • A Key ID

These are stored in the mobile app and used for all future signed requests by the end customer.

Refer - Add User API Key

This secure and preferred approach uses OTP validation for email verification.

  1. Middleware calls initiateDeviceRegistration API:

    • Passes the end user's email address.
    • XD Ledger sends an OTP to the email.

  2. End Customer receives the OTP.

  3. Middleware or Mobile App calls completeDeviceRegistration API with:

    • The OTP
    • Public Key (generated on the mobile app)

  4. XD Ledger returns:

    • API Key
    • Key ID

These are stored on the mobile device and used for subsequent signed requests.