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
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)

curl https://api.cognisafe.uk/api/requests \
  -H "X-Cognisafe-Key: csk_your_key_here"

Authorization: Bearer header

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():

export COGNISAFE_API_KEY="csk_your_key_here"

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

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.

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:

openssl rand -hex 32

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