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

# Authentication

> Create and manage API keys for programmatic access

## API keys

API keys let you access the Animus API from scripts, CI/CD pipelines, or custom integrations. Each key is scoped to specific permissions and tied to your account.

### Creating a key

1. Open the [Animus app](https://app.animus.so/integrations)
2. Go to **Integrations**
3. Under **API Keys**, click **Create**
4. Give your key a name (e.g. "My CLI Key")
5. Select the permissions you need
6. Click **Create Key** and copy the key immediately — it won't be shown again

### Using your key

Send the key as a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.animus.so/api/v1/content/recent \
  -H "Authorization: Bearer anm_your_api_key_here"
```

All API keys are prefixed with `anm_` so they're easy to identify.

## Scopes

Each API key has one or more scopes that control what it can access:

| Scope    | Description                                        | Example endpoints                          |
| -------- | -------------------------------------------------- | ------------------------------------------ |
| `read`   | Read content, collections, and library stats       | `GET /content/recent`, `GET /collections`  |
| `write`  | Create, update, and delete content and collections | `POST /content`, `DELETE /collections/:id` |
| `search` | Search across your library                         | `GET /search`                              |

If a key doesn't have the required scope for an endpoint, the API returns `403 Forbidden`.

<Tip>Start with only the scopes you need. You can always update a key's scopes later.</Tip>

## Managing keys

You can have up to **10 active API keys** per account.

* **Revoke** a key to immediately disable it. Any application using the key will lose access.
* **Update** a key to change its name or scopes without regenerating the secret.

Both actions are available in the Integrations page of the Animus app, or via the API:

```bash theme={null}
# List your keys
curl https://api.animus.so/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Revoke a key
curl -X DELETE https://api.animus.so/api/v1/api-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

<Warning>API key management endpoints require JWT authentication (your session token), not an API key. API keys cannot manage other API keys.</Warning>

## Security best practices

* Never commit API keys to version control
* Use environment variables to store keys
* Create separate keys for different applications
* Revoke keys you no longer need
* Use the minimum scopes required for each integration