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

# Authentication

> How to authenticate with the Clustr API

All API requests require a Bearer token in the `Authorization` header.

```
Authorization: Bearer <your_api_key>
```

## Creating an API key

1. Go to the [API settings page](https://app.clustr-ai.com/settings/api)
2. Click **Create New Key**
3. Copy the key immediately. It won't be shown again

You can create up to 10 API keys per workspace.

## Check a key

`GET /api/public/test-key` answers `200` with your workspace id when the key works. Tools that
offer a "test connection" button can call it.

```bash theme={null}
curl https://api.clustr-ai.com/api/public/test-key \
  -H "Authorization: Bearer $CLUSTR_API_KEY"
```

## Example

```bash cURL theme={null}
curl https://api.clustr-ai.com/api/public/target-accounts \
  -H "Authorization: Bearer clstr_abc123..."
```

```python Python theme={null}
import requests

headers = {"Authorization": "Bearer clstr_abc123..."}
response = requests.get(
    "https://api.clustr-ai.com/api/public/target-accounts",
    headers=headers
)
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.clustr-ai.com/api/public/target-accounts",
  { headers: { Authorization: "Bearer clstr_abc123..." } }
);
```

```go Go theme={null}
req, _ := http.NewRequest("GET",
    "https://api.clustr-ai.com/api/public/target-accounts", nil)
req.Header.Set("Authorization", "Bearer clstr_abc123...")
resp, _ := http.DefaultClient.Do(req)
```

## Error responses

| Status | Meaning |
| - | - |
| `401` | Missing or invalid API key |
| `403` | API key does not have access to this resource |

## Signing in from the Clustr web app

The Clustr web app does not use API keys and holds no token. It sends the person to
`GET /api/auth/login?return_to=/accounts`, which goes to the Clustr sign-in page and back, and
leaves a session in a secure, httpOnly cookie on `api.clustr-ai.com`. The app then calls the API
with the browser's credentials (`credentials: 'include'`), and `POST /api/auth/logout` signs out.

These routes are for the Clustr app only: a change made with the session cookie must come from the
app's own address, and any other is refused with `403`. Integrations keep using API keys as above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.