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

# Authentication & Security

> API keys, scopes, rate limits, and security best practices.

## API keys

All requests to `api.thrindex.com` are authenticated with a Bearer token. API keys are created in the [dashboard](https://app.thrindex.com) and scoped to an organization.

```
Authorization: Bearer th_live_<64 hex characters>
```

API keys start with `th_live_` followed by 64 hexadecimal characters (32 random bytes). This is the only authentication method accepted by the memory API.

<Warning>
  Keys are shown **once** when created. Copy and store them securely — they cannot be retrieved again. If you lose a key, revoke it and create a new one.
</Warning>

***

## Scopes

Each key is granted a subset of the following scopes. Only request the scopes your agent actually needs.

| Scope           | Grants access to                                                                            |
| --------------- | ------------------------------------------------------------------------------------------- |
| `memory:write`  | `POST /v1/memories` — store new memories                                                    |
| `memory:read`   | `POST /v1/memories/search`, `GET /v1/memories`, `GET /v1/memories/{id}` — retrieve memories |
| `memory:delete` | `DELETE /v1/memories/{id}` — delete memories                                                |

### Missing scope errors

When a valid key is used for an endpoint it does not have scope for, the API returns `401` with error code `forbidden`:

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "missing required scope: memory:write",
    "request_id": "req_01j..."
  }
}
```

This is distinct from `unauthorized` (invalid or missing key), which is also `401` but with code `unauthorized`.

***

## Rate limits

Rate limits are enforced per API key. When a key exceeds its configured request rate, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded",
    "request_id": "req_01j..."
  }
}
```

The response includes a `Retry-After: 1` header indicating how many seconds to wait before retrying. Both the Python and TypeScript SDKs respect this header automatically and retry without blocking.

***

## Security best practices

### Keep keys server-side

API keys must only be used from your backend. Never put them in:

* Browser JavaScript or browser bundles
* Mobile app binaries
* Public repositories or commit history
* Client-side configuration files

### One key per environment

Use separate keys for production, staging, and development. This limits the blast radius of any leak and lets you revoke individual environments without disrupting others.

### Store keys in secrets managers

Use environment variables backed by a secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, etc.) or your platform's native secret store (Vercel environment variables, Railway secrets, etc.).

```bash theme={null}
# In your deployment environment
export THRINDEX_API_KEY="th_live_..."
```

```python theme={null}
import os
from thrindex import Thrindex

client = Thrindex(api_key=os.environ["THRINDEX_API_KEY"])
```

### Rotate after a leak

If a key is compromised:

1. Create a new key with the same scopes.
2. Deploy the new key to all services.
3. Revoke the old key from the dashboard.

Do not wait to revoke — a key remains valid until explicitly revoked.

***

## Data isolation

Every API key is tied to exactly one organization. The `org_id` is derived from the key during authentication and is never accepted from the request body. A key cannot read or write data belonging to another organization — this is enforced at the database level.

***

## What the API key is not

The credential you use to log into [app.thrindex.com](https://app.thrindex.com) (your email and password) is a completely separate auth system. Dashboard sessions cannot be used as Bearer tokens for the memory API, and API keys cannot be used to log into the dashboard.