Authentication

All API requests require authentication via API key, unless running in development mode with AUTH_DISABLED=true.

API key format

Keys are prefixed for identification: dsp_sk_<random-32-hex-chars>

The server stores only the SHA-256 hash of the key. The plaintext key is shown once on creation and cannot be retrieved again.

Sending your key

Include the key in the Authorization header:

Authorization: Bearer dsp_sk_abc123...

Per-user scene isolation

Each API key is associated with an ownerId. Scenes created with a key are only accessible to that key’s owner. Attempting to access another user’s scene returns 404.

Creating API keys

Bootstrap key

Set the BOOTSTRAP_API_KEY environment variable to create an initial key on server start:

BOOTSTRAP_API_KEY=my-secret-key pnpm --filter @zindex/api start

Programmatic key creation

curl -s https://api.zindex.ai/v1/auth/keys \
  -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production Key" }'

Rate limiting

Each API key is rate-limited to prevent abuse:

When exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Response headers on every request:

• X-RateLimit-Remaining — requests remaining in the current window
• X-RateLimit-Reset — seconds until the limit resets

Environment variables