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
- Generate an Ed25519 key pair for the installation. Keep the private key in protected storage.
- Send the public key to
POST /v3/challengewith the AppKey. - Keep the returned
payloadstring exactly as received. The challenge lasts two minutes and can be used once. - 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. Appendemailonly for registration when supplied. - Serialize
{ "challenge": payload, "operation": operation }as compact JSON and sign its UTF-8 bytes with Ed25519. Base64-encode the signature. - 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:
Sign the compact JSON object below in this property order:
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.

