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

# Authentication

> Authenticating with the Cognisafe API.

## API key format

Cognisafe API keys use the `csk_` prefix followed by a 48-character hex string:

```
csk_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3
```

Keys are scoped to a **project** — each key is associated with exactly one project and can only access data for that project.

## Creating a key

1. Sign in at [cognisafe.uk](https://cognisafe.uk)
2. Navigate to your project → **API Keys**
3. Click **Create key**
4. Copy the key immediately — it is shown only once

You can create multiple keys per project (e.g., one for production, one for CI, one per environment).

## Passing the key

### `X-Cognisafe-Key` header (recommended)

```bash theme={null}
curl https://api.cognisafe.uk/api/requests \
  -H "X-Cognisafe-Key: csk_your_key_here"
```

### `Authorization: Bearer` header

```bash theme={null}
curl https://api.cognisafe.uk/api/requests \
  -H "Authorization: Bearer csk_your_key_here"
```

Both formats are accepted. `X-Cognisafe-Key` is preferred for clarity.

### SDK (environment variable)

When using the Python or Node.js SDK, set the key as an environment variable rather than passing it to `configure()`:

```bash theme={null}
export COGNISAFE_API_KEY="csk_your_key_here"
```

The SDK reads `COGNISAFE_API_KEY` automatically if `api_key` is not passed to `configure()`.

<Warning>
  Never commit API keys to source control. If a key is accidentally committed, rotate it immediately via the dashboard (**API Keys** → **Rotate**) and update your environment variables. Rotated keys are invalidated within 60 seconds.
</Warning>

## Key rotation

Keys can be rotated without downtime:

1. Create a new key in the dashboard
2. Update your environment variables / secrets manager with the new key
3. Deploy / restart your application
4. Delete the old key from the dashboard

## Revoking a key

In the dashboard: **API Keys** → find the key → **Revoke**. The key is invalidated immediately. Any requests using the revoked key receive `HTTP 401 Unauthorized`.

## Internal API secret

The `INTERNAL_API_SECRET` environment variable is a separate secret used for server-to-server authentication between the `web` (Next.js) and `api` (FastAPI) services. It is not an API key and is never exposed to end users or SDK clients. Generate it with:

```bash theme={null}
openssl rand -hex 32
```

Set the same value on both the `api` and `web` services.