Use the quickstart for a working login. This page documents the exact values that are signed.
Include the Referer header on every request, including signed login and account-creation requests and calls from a backend.
Login
Create a new nonce and build this UTF-8 string:
Compute Base64-encoded HMAC-SHA-256 using the account password as the HMAC key. Send userName, nonce, signature, and seconds to POST /Agent/Account/Login.
The host value must exactly match the HTTP host used for the request, including a non-default port and excluding the scheme and path.
Account creation
Account creation is for a trusted backend that has an operator-issued Agent API key and secret. Without a phone number, sign:
With a phone number, sign:
Use the API secret as the HMAC key. Send the matching fields to POST /Agent/Account/Create. The field order, capitalization of values, empty values, and host must be identical between the message and request.
Do not put an account-creation API secret in a browser, mobile application, public repository, or downloadable client. Use the browser-based onboarding flow or a trusted backend.
JWTs
Successful login returns a short-lived JWT. Send it on authenticated calls:
- Keep JWTs out of URLs and logs.
- The specification describes
Account/Refresh and Account/Logout; verify their lifecycle behavior on the target deployment before relying on refresh or immediate invalidation.
- Treat a stolen JWT as an active credential until it expires or its deployment has demonstrably invalidated it.
HMAC test vector
Use this deterministic vector to verify an implementation without contacting a Neuron:
Use this fixed nonce only for the test vector. Generate a fresh cryptographic nonce for every real login request.
Common signature failures
