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

# Authentication

> How API keys work, how to manage them, and how to debug auth errors.

The Seyn API authenticates every request with a **bearer API key**. Each key belongs to exactly one organisation; there are no cross-organisation keys.

## Key format

Seyn keys are random tokens prefixed with `sk_live_`:

```
sk_live_f50f2ffc52a6cc68ea9925d3f25052db8c1cbd44
```

Send the key in an `Authorization` header on every request:

```http theme={null}
Authorization: Bearer sk_live_f50f2ffc52a6cc68ea9925d3f25052db8c1cbd44
```

The SDK does this for you automatically: you just pass `{ apiKey }` to the constructor.

## Creating a key

1. Sign in at [app.seynlabs.com](https://app.seynlabs.com).
2. Open **Settings → API Keys**.
3. Click **Create**, give it a label.
4. Copy the full `sk_live_*` token from the modal. **This is the only time the full token is visible**: Seyn only stores its SHA-256 hash plus the first 8 characters (the prefix) for display.

<Warning>
  If you close the modal without copying the token, the key is unrecoverable. Revoke it and create a new one.
</Warning>

## Org admins can manage keys

Anyone with the `org:admin` role in your Seyn organisation can create and revoke keys for that organisation. `org:member` accounts can use the API but can't manage keys.

## Rotation

There's no "edit" or "renew" operation: keys are immutable. To rotate:

1. Create a new key.
2. Deploy your services with the new key.
3. Once you're confident every caller is on the new key, **revoke** the old one in the same dashboard.

Revocation takes effect immediately. The next request with the revoked key will get a `403 KEY_REVOKED` response.

## Where to use a key

* **Server-side only.** API keys grant read access to your entire organisation's extracted knowledge. Treat them like database credentials.
* **Environment variables** or your secret store (HashiCorp Vault, AWS Secrets Manager, 1Password, etc.). Never commit a key.
* **Never in browsers or mobile apps.** If you need browser-side queries, proxy through your own backend that reads the key from its environment.

## Error codes

| HTTP | Code                  | What it means                                     | What to do                                                       |
| ---- | --------------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
| 401  | `MISSING_AUTH_HEADER` | No `Authorization` header, or wrong scheme        | Check your request actually includes `Authorization: Bearer ...` |
| 401  | `INVALID_API_KEY`     | The token doesn't match any key we know about     | Re-check what you copy/pasted; maybe a key got truncated         |
| 403  | `KEY_REVOKED`         | The token *was* valid but has been revoked        | Ask your org admin to issue a new one, or create one yourself    |
| 429  | `RATE_LIMITED`        | More than 60 requests in 60 seconds from this key | Back off and retry, or [request a higher limit](#rate-limits)    |

The `INVALID` vs `REVOKED` distinction is deliberate. If you see `INVALID_API_KEY`, the bug is on your side: check what you pasted. If you see `KEY_REVOKED`, the bug is upstream: talk to your admin.

## Rate limits

Default: **60 requests per minute per key**. A 429 with `code: "RATE_LIMITED"` is returned when you exceed it.

If your integration needs higher throughput (large backfills, real-time chat, BI workloads), email [support@seynlabs.com](mailto:support@seynlabs.com) with your use case and we'll raise the limit on specific keys.

The SDK does not retry on 429s; wrap your calls with your own retry-with-backoff if needed.

## Multi-tenancy

Each API key is scoped to one Seyn organisation. Even if your account belongs to multiple organisations in Seyn, a given key only sees one of them. Every query is implicitly filtered to that org server-side, so there is no way to leak data across organisations via API access.