# 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
}
```