All documentation

Authentication

API keys, Web SDK tokens, and secure key handling.

Download Markdown
GuidesAPI ReferenceCode ExamplesBest Practices

Authentication

Overview

Naiza public APIs use two auth modes:

  • API key auth (x-api-key) for /api/v1/* server-to-server integrations
  • Bearer auth (Authorization: Bearer <token>) for POST /api/v1/websdk/signals using short-lived SDK tokens

API Key Authentication

Include your key in every API request:

POST /api/v1/decisions/evaluate
x-api-key: naiza_api_sk_live_...
Content-Type: application/json

First Auth Check

curl -X GET "https://api.naiza.ai/api/v1/decisions?limit=1" \
  -H "x-api-key: naiza_api_sk_live_YOUR_KEY"

Web SDK Authentication Flow

  1. Your backend calls POST /api/v1/websdk/tokens with x-api-key
  2. Naiza returns a short-lived token (about 15 minutes)
  3. Browser SDK sends signal batches to POST /api/v1/websdk/signals with Authorization: Bearer <token>
  4. API keys never leave your server

Secure Key Management

  • Keep keys in a secret manager or server-side environment variables
  • Never ship keys in frontend bundles, mobile binaries, or logs
  • Rotate keys regularly and immediately after suspected compromise
  • Use separate keys for dev, staging, and production

401 Unauthorized

Common causes:

  • Missing x-api-key
  • Revoked or invalid key
  • Key belongs to a different tenant
  • Expired/invalid Web SDK bearer token

Example response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": {}
  }
}

Related Docs