> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leapfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How Lola Send authenticates every sender and secures every session before any agent interaction.

Every inbound message passes through Lola Send's authentication pipeline before reaching any agent. The middleware chain normalizes sender identity, queries the identity service, and injects verified metadata into the message context. No unauthenticated message reaches an agent.

## Message authentication flow

<Steps>
  <Step title="Message arrives via channel connector">
    The inbound message enters through a channel connector (WhatsApp, Telegram) and is normalized into Celai's internal message format.
  </Step>

  <Step title="Command authorization check">
    `CommandsAuthMiddleware` inspects the message for slash commands. If the message is a command, it verifies whether commands are enabled for this deployment and whether the command is authorized.
  </Step>

  <Step title="Phone number normalization">
    `PayhubAuthMiddleware` normalizes the sender's phone number to a standard international format before any identity lookup occurs.
  </Step>

  <Step title="Identity service query">
    `PayhubAuthMiddleware` queries the identity service using the normalized phone number to fetch the sender's profile and compliance status.
  </Step>

  <Step title="Identity found — metadata injection">
    If the sender is found, their identity is injected into the message metadata as a `ContextUser` object containing verification status, payment method summaries, and identity details. The message proceeds to the LogicRouter for agent selection.
  </Step>

  <Step title="Identity service unavailable — graceful degradation">
    If the identity service returns a `404` or is unreachable, the `unavailable_service` flag is set on the message metadata. The message is not blocked — it is routed to the service unavailable agent for graceful degradation.
  </Step>

  <Step title="LogicRouter evaluates authenticated identity">
    The LogicRouter reads the authenticated identity from the message metadata and selects the appropriate agent: onboarding, sender home, blocked, pending CIP, or service unavailable.
  </Step>
</Steps>

## Phone normalization

All phone numbers are normalized to a standard international format before any identity lookup. This prevents identity spoofing through different phone number format representations.

For example, `+1-555-0100`, `15550100`, and `+15550100` all resolve to the same canonical form before the identity service is queried. Without normalization, a sender could potentially present different identities by varying their phone number format.

<Warning>
  Phone normalization runs before the identity lookup. If normalization logic is misconfigured, the identity service query will fail to match the sender, routing them to the onboarding flow instead of their verified agent. This is a fail-safe behavior — the sender never gains elevated access due to a normalization failure.
</Warning>

## ContextUser

The authenticated sender object provides agents with the following verified data:

| Field                    | Description                                                                    |
| ------------------------ | ------------------------------------------------------------------------------ |
| Identity                 | Sender's name, phone number, and internal identifier from the identity service |
| Verification status      | Compliance verdict: `passed`, `pending`, or `blocked`                          |
| Card payment methods     | Display names only (e.g., "Visa ending 1234") — no raw card data               |
| Payment method summaries | Available payment method types and their display identifiers                   |

Agents receive this object as part of the message context. They cannot modify it, and they cannot access fields beyond what the identity service provides.

## Session tokens

JWT tokens with EC key pairs secure communication between Lola Send and the frontend web widgets used for identity verification and card authorization:

| Property  | Details                                                     |
| --------- | ----------------------------------------------------------- |
| Algorithm | Elliptic curve (EC) key pairs                               |
| Scope     | Bound to a specific ticket ID and operation context         |
| Payload   | Ticket ID, CIP services URL, theme URL, fail callback URL   |
| Lifetime  | Short-lived — scoped to a single widget interaction session |

Tokens are generated when the agent creates a ticket for an out-of-band operation (CIP verification, card authorization). The widget uses the token to authenticate its requests to Lola Send's callback endpoints.

<Note>
  Authentication is non-blocking by design. If the identity service is unavailable, the sender is routed to a graceful degradation agent rather than receiving an error. This ensures the messaging channel remains responsive even during backend outages.
</Note>

## Configuration and control

The bank controls several aspects of the authentication pipeline:

| Mechanism             | What the bank configures                                                                      |
| --------------------- | --------------------------------------------------------------------------------------------- |
| Identity service      | The backend identity service that `PayhubAuthMiddleware` queries — the bank owns this service |
| Middleware ordering   | The sequence of authentication middleware in the pipeline                                     |
| Command authorization | Whether slash commands are enabled and which commands are allowed                             |
| Channel allowlisting  | Which phone numbers can interact with Lola Send in a given deployment                         |
| JWT key pairs         | EC key pairs used for widget session tokens                                                   |