API Keys & Authentication

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

Overview

Stream API includes a key management and rate-limiting system backed by SQLite. When enabled, client apps must supply an authenticated key to establish SSE streams or request proxied media.

Key Tiers

pk_ (Partner Key): For high-volume frontends. Default: 1,000 req/min.
sk_ (Standard Key): For private self-hosters and internal client apps. Default: 500 req/min.
pub_ (Public Key): For public trial access or open community frontends. Default: 10 req/min.

Creating Keys

Generate keys using the CLI tool in the Stream API directory:

node add-key.mjs standard 500 my-desktop-client
node add-key.mjs partner 1000 partner-frontend
node add-key.mjs public 10 public-guest

Output Example

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

Database Export & Sync

For automated deployments, export the database to JSON:

node export-db.mjs

This dumps active keys to db.json:

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

To sync edits from db.json back into SQLite:

node update-db.mjs

Client Authorization

Clients can send their key via headers or query parameters:

Authorization Header

GET /movie?id=155 HTTP/1.1
Host: api.vyla.cc
Authorization: Bearer sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3

Custom Header

X-API-Key: sk_8f14b2d39a7e4c5b10e9f8a7b6c5d4e3

Query Parameter

Used for browser EventSource and native <video> elements that do not support custom request headers:

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

Rate Limit Responses

Responses include standard rate-limiting headers:

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

When a quota is exceeded, Stream API returns HTTP 429:

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

2.3 KiB Raw Blame History