huge rewrite

stream-api/authentication/index.md

@@ -0,0 +1,125 @@
+# API Keys & Authentication
+
+<p class="page-description">Managing API keys, rate limits, SQLite database synchronization, and authorization headers in Stream API.</p>
+
+## 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:
+
+```bash
+# 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
+```bash
+node export-db.mjs
+```
+This dumps the active SQLite database tables into `db.json`:
+```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:
+```bash
+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)
+```http
+GET /movie?id=155 HTTP/1.1
+Host: your-api.example.com
+Authorization: Bearer sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3
+```
+
+### 2. Custom API Key Header
+```http
+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:
+```http
+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
+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:
+```json
+{
+  "error": "Rate limit exceeded. Please retry in 32 seconds.",
+  "retry_after": 32
+}
+```