documentation/stream-api/authentication/index.md

API Keys & Authentication

Managing API keys, rate limits, SQLite database synchronization, and authorization headers in Stream API.

Overview

Stream API includes a built-in cryptographic key management and rate-limiting system backed by SQLite. When enabled, client applications must supply an authenticated key to establish Server-Sent Events connections or request proxied media streams.

---

Key Structure & Prefixes

API keys are 32-character hexadecimal strings generated with a specific prefix indicating the client tier:

Key Prefix	Key Type	Intended Use Case	Default Rate Limit
pk_	Partner Key	Verified high-volume partner frontends and applications	1,000 req / minute
sk_	Standard Key	Private self-hosters and internal client instances	500 req / minute
pub_	Public Key	Anonymous public trial access or open community frontends	10 req / minute

---

Generating API Keys via CLI

The Stream API repository includes a CLI tool (add-key.mjs) to generate and insert keys into the active SQLite database:

# Syntax: node add-key.mjs <type> <rate_limit_per_min> <client_name>

# 1. Create a Standard Key for a personal desktop client:
node add-key.mjs standard 500 my-desktop-client

# 2. Create a Partner Key for a high-traffic community player:
node add-key.mjs partner 1000 partner-frontend

# 3. Create a restricted Public Key:
node add-key.mjs public 10 public-guest

CLI Output Example

Generated Key: sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3
Type: standard
Limit: 500 req/min
Client: my-desktop-client
Status: Active

The key is printed once upon creation. Copy and deliver it to your client application securely.

---

Managing Keys via JSON Database Export

For automated deployments or bulk key management, you can export the database to a JSON file:

1. Export Database

node export-db.mjs

This dumps the active SQLite database tables into db.json:

{
  "keys": [
    {
      "key": "sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3",
      "type": "standard",
      "limit": 500,
      "client": "my-desktop-client",
      "active": 1,
      "created_at": "2026-11-14T12:00:00Z"
    }
  ]
}

2. Modify and Re-Import

Edit db.json to add, revoke, or modify limits, then commit the changes back to SQLite:

node update-db.mjs

---

Client Authorization Headers

Clients can authenticate requests by passing the key in one of the following locations:

1. Authorization Header (Recommended)

GET /movie?id=155 HTTP/1.1
Host: your-api.example.com
Authorization: Bearer sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3

2. Custom API Key Header

X-API-Key: sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3

3. Query Parameter (for EventSource & HTML5 Video)

Because native browser EventSource and <video> tags do not support custom request headers, you can pass the key as a query parameter:

GET /movie?id=155&key=sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3 HTTP/1.1

---

Rate Limit Headers

When requests are evaluated, Stream API returns standard rate-limiting headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 498
X-RateLimit-Reset: 1731614460

If a client exceeds their tier quota, Stream API responds with HTTP 429:

{
  "error": "Rate limit exceeded. Please retry in 32 seconds.",
  "retry_after": 32
}