Authentication

Most API requests require authentication via API key. Public endpoints (validate, render, normalize) do not require a key - see Endpoints for details.

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

Use the key management endpoint to create additional keys:

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

The response includes the new key - store it securely, as it cannot be retrieved again.

Rate limiting

All endpoints are rate-limited to prevent abuse. Authenticated and public endpoints have separate tiers:

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