mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
126 lines
3.4 KiB
Markdown
126 lines
3.4 KiB
Markdown
# 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
|
|
}
|
|
```
|