Skip to main content

​
API keys

The Neuron Agent API uses a two-step authentication model:
  1. HMAC-signed requests — account creation and login use an HMAC signature to prove ownership of your API key without transmitting the secret.
  2. JWT bearer tokens — once logged in, all subsequent requests use a short-lived JWT in the Authorization header.

​
HMAC signing

Account creation (Account/Create) and login (Account/Login) are authenticated by signing a nonce with your API secret using HMAC-SHA-256.

​
Signing steps

  1. Obtain a nonce — a unique string (e.g., a random UUID or timestamp-based value). Never reuse a nonce.
  2. Compute the HMAC-SHA-256 digest of the nonce using your API secret as the key.
  3. Base64-encode the digest to produce the signature.
  4. Include apiKey, nonce, and signature in your request body.
The API key and secret are issued by your Neuron operator. Do not confuse them with the JWT token used after login.

​
JWT bearer tokens

After a successful login, the API returns a JWT and an expiry time (up to 3600 seconds). Use the JWT in the Authorization header for all subsequent requests:

​
Token lifecycle

  • Tokens expire — call Account/Refresh before expiry to get a new JWT without logging in again.
  • Once expired, call Account/Login again.
  • Call Account/Logout to immediately invalidate a token.

​
Security best practices

  • Never expose your API secret in client-side code or public repositories.
  • Use a cryptographically random nonce for every signing operation.
  • Store JWTs in memory only — not in persistent storage — where possible.
  • Refresh tokens proactively before they expire rather than waiting for a 401.
See Security and Transport for additional recommendations including TLS requirements and rate limits.