Skip to navigation

Request signing

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:

HeaderValue
X-AuthlyX-NonceFresh lowercase hexadecimal nonce, 32 to 128 characters
X-AuthlyX-TimestampServer-aligned Unix milliseconds as a 13-digit string
X-AuthlyX-SignatureBase64 Ed25519 signature

Sign the compact JSON object below in this property order:

{
"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.