Authenticate with XYB Ledger

To ensure secure access, all requests to the Ledger system must be authenticated. This means your service must prove its identity using a signed JSON Web Token (JWT), tied to a registered identity called an agent.

This guide explains how Ledger authentication works and outlines the steps your team needs to follow to connect securely and successfully.

What Is the Authentication Model?

The Ledger uses a public key authentication model, where each client proves its identity using signed JWTs and registered keys:

  • You (the client) generate your own cryptographic keys

  • You send your public key to XYB

  • You sign each API request using your private key

  • The Ledger validates your request using the stored public key

This model is secure and optimized for high-volume, direct integrations.

Key Concepts

Agent

An agent is your registered identity within the Ledger system. It represents your service and is included in all authenticated requests. Agents are defined using an entity reference, in the format:

<role>/<reference>

JWT Token

Each request to the Ledger must include:

  • The xyb-agent header when acting as an application or employee (e.g., using tools like Luca).

Your JWT must:

Include a sub (subject) claim that matches the value of xyb-agent

  • Be signed using your registered private key

  • Be short-lived (recommended: 5–15 minutes)

⚠️ service/ prefixes are reserved for internal services only. For customer use:

  • Use application/ for apps

  • Use employee/ for individual users

What You Need to Do

1. Choose the agent Name - a unique identity that represents your app or service.

Your agent name must meet these requirements:

  • Must begin with ext-

  • All lowercase (a–z)

  • Max 14 characters

  • Must be globally unique

Example: ext-invoice, ext-payroll, etc.

2. Generate a Key Pair

You must generate a JWK key pair (public/private key). Supported types include:

  • RSA (e.g. RS256)

  • EC (e.g. ES256)

  • EdDSA (Ed25519)

Store your private key securely. Never share it.

3. Send Your Public Key to XYB

Email your public JWK and chosen service name to your XYB account manager at:

📧 [email protected]

Your key will be registered in our system within 2 business days.

4. Sign API Requests

Each request to the Ledger must include:

Header
Description

xyb-agent

Your agent path

Authorization

Bearer <your signed JWT>

request-id

A unique request ID (UUID format)

You may also include the xyb-source header (your service name) if your service is acting on behalf of another agent. In that case, the service agent must have the impersonate permission.

Key Rotation and Revocation

  • To rotate a key:

    1. Email your new public key

    2. Then send a second email specifying the key ID to revoke

  • To revoke a key: Email your account manager with the key ID and service name.

SLA:

  • 2 business days for standard requests

  • Immediate for security incidents

Security & Monitoring

  • Private keys must be stored securely on your side

  • We maintain audit logs for all authentication activity

  • Key rotation is recommended every 3–6 months

Last updated