---
title: "Authentication"
description: "API keys, Web SDK tokens, and secure key handling."
collection: "api-reference"
slug: "authentication"
url: "https://naiza.ai/docs/api-reference/authentication"
markdown: "https://naiza.ai/docs/api-reference/authentication.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Authentication

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

## Table of contents

- [Overview](#overview)
- [API Key Authentication](#api-key-authentication)
  - [First Auth Check](#first-auth-check)
- [Web SDK Authentication Flow](#web-sdk-authentication-flow)
- [Secure Key Management](#secure-key-management)
- [401 Unauthorized](#401-unauthorized)
- [Related Docs](#related-docs)

## 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:

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

### First Auth Check

```bash
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:

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

## Related Docs

- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md)
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md)
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md)

## Related documentation

- [API Overview](https://naiza.ai/docs/api-reference/overview.md) — Base URL, versioning, and high-level API surface.
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md) — Browser SDK endpoints and device signal collection.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [Sessions API](https://naiza.ai/docs/api-reference/sessions.md) — Session grouping and timeline endpoints.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).
- [Lists API](https://naiza.ai/docs/api-reference/lists.md) — Allowlists, blocklists, and list membership management.

---

*Source: [https://naiza.ai/docs/api-reference/authentication](https://naiza.ai/docs/api-reference/authentication) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*