> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Neuron API using API keys and tokens.

## 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.

```text theme={null}
signature = BASE64( HMAC-SHA256(secret, nonce) )
```

<Note>
  The API key and secret are issued by your Neuron operator. Do not confuse them with the JWT token used after login.
</Note>

## 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:

```text theme={null}
Authorization: Bearer {token}
```

### 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`.

<Info>
  See [Security and Transport](/neuron-api/security-and-transport) for additional recommendations including TLS requirements and rate limits.
</Info>