> This page is for version V3 - Beta (default).
> For other versions, use one of these documentation indexes:
> - V3 - Beta (default): https://docs.authlyx.dev/v3/llms.txt
> - V2 - Legacy: https://docs.authlyx.dev/v2/llms.txt
> - V1 - End of support: https://docs.authlyx.dev/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.authlyx.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.authlyx.dev/_mcp/server.

# Request signing

> How V3 binds sessions and requests to an installation.

Use the SDK unless you are implementing a new client. Signatures bind the request to an installation key; they do not prove that the software cannot be modified.

## Login challenge

1. Generate an Ed25519 key pair for the installation. Keep the private key in protected storage.
2. Send the public key to `POST /v3/challenge` with the AppKey.
3. Keep the returned `payload` string exactly as received. The challenge lasts two minutes and can be used once.
4. Normalize the login operation in this exact property order: `type`, `appKey`, `version`, `sid`, `hash`, `username`, `password`, `licenseKey`. Use empty strings for unused credentials and a missing hash. Append `email` only for registration when supplied.
5. Serialize `{ "challenge": payload, "operation": operation }` as compact JSON and sign its UTF-8 bytes with Ed25519. Base64-encode the signature.
6. Send the login operation, challenge ID and signature to `/v3/login`.

The order and exact bytes matter. Do not log that proof payload: it includes sign-in credentials. The public key supplied during challenge creation determines which installation can consume it.

## Protected requests

Send `Authorization: Bearer SESSION_TOKEN` and these headers:

| Header                | Value                                                   |
| --------------------- | ------------------------------------------------------- |
| `X-AuthlyX-Nonce`     | Fresh lowercase hexadecimal nonce, 32 to 128 characters |
| `X-AuthlyX-Timestamp` | Server-aligned Unix milliseconds as a 13-digit string   |
| `X-AuthlyX-Signature` | Base64 Ed25519 signature                                |

Sign the compact JSON object below in this property order:

```json
{
  "type": "authlyx.request.v3",
  "method": "POST",
  "path": "/v3/session/check",
  "bodySha256": "SHA256_OF_EXACT_BODY_BYTES",
  "nonce": "FRESH_NONCE",
  "timestamp": "UNIX_MILLISECONDS",
  "tokenHash": "SHA256_OF_SESSION_TOKEN"
}
```

The hash values are lowercase hexadecimal. The timestamp is a string, not a JSON number. The signature covers the exact method, pathname, body hash, nonce, time and token hash. The server rejects requests outside its two-minute timestamp window and rejects reused nonces within their retention window.

A session stays tied to its original application, identity, system ID and installation public key. Adding another username to a request cannot change who the session represents.

## Verify a server response

Verify `verification.signature` over the exact UTF-8 `verification.signedPayload` using the trusted Ed25519 key identified by `keyId`. Then check its HTTP status, request method, path, nonce and body hash against your request. Check that its embedded response matches the outer response before using any access data.

The SDK carries trusted public keys. A key returned by the same untrusted response cannot establish trust by itself. Keep support for planned key rotation. Health/readiness responses are not signed. Signing failures may return an unsigned `SIGNING_UNAVAILABLE` response; that must never grant access.

## Offline permit proof

An offline challenge uses the existing session's installation key. Its operation is `{ "action": "offlinePermit", "sessionId": "CURRENT_SESSION_ID" }`. Sign it with the exact challenge string as above. The returned permit has its own signature and expiry checks.