> For the complete documentation index, see [llms.txt](https://docs.getlimy.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getlimy.ai/rest-api/authentication.md).

# Authentication

## Authentication

Limy's REST API does **not** accept your static API key directly. Instead, you exchange the static key for a short-lived **session token** (a JWT), and use that session token on every API request. This two-step model lets us revoke compromised keys instantly without invalidating in-flight traffic, and keeps long-lived secrets off the wire on every call.

#### Step 1 — Exchange your static key for a session token

Send the static key as a Bearer token to the exchange endpoint:<br>

```bash
curl -X POST https://api.limy.ai/v1/auth/accesskey/exchange \
  -H "Authorization: Bearer <YOUR_STATIC_API_KEY>"
```

Successful response:

```json
{
  "keyId": "K3EfyZac4vZdEMC1VIodMSguN5Ro",
  "sessionJwt": "eyJhbGciOiJSUzI1NiIs..."
}
```

* `keyId` — identifier of the static key that issued this session. Useful for logging which key your service is currently using.
* `sessionJwt` — the token you'll send to the Limy API. Treat it like a password. Its expiry (`exp` claim) is encoded in the JWT itself&#x20;

{% hint style="info" %}
Always cache the JWT and reuse it until close to its `exp` time — do not exchange on every API call.
{% endhint %}

#### Step 2 — Call the Limy API with the session token

Send the `sessionJwt` as a Bearer token on every API request:

```bash
curl https://api.limy.ai/v1/<endpoint> \
  -H "Authorization: Bearer <SESSION_JWT>"
```

If the token is missing, malformed, or expired, the API returns `401 Unauthorized`.

#### Error responses

| Status                                              | Meaning                                       | What to do                                                                                                   |
| --------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized` on `/v1/auth/accesskey/exchange` | Static key is invalid, revoked, or expired    | Generate a new key in the admin panel                                                                        |
| `401 Unauthorized` on a Limy API call               | Session JWT is missing, malformed, or expired | Re-exchange the static key and retry                                                                         |
| `429 Too Many Requests`                             | API key rate/quota reached                    | Retry with exponential backoff on `429` rate limit errors. For daily quota exhaustion, retry after 24 hours. |

####