Authentication

How to authenticate requests to your self-hosted Vyla API instance.

Overview

Since Vyla API is self-hosted, you manage your own API keys and authentication. The API supports two authentication methods depending on your use case.

Method	Header	Use case
Session token	X-Session-Token	Browser players and client-side apps
API key	Authorization or X-API-Key	Server-side integrations and direct API access

You must set up your own API keys when deploying your Vyla API instance. See Self-Hosting for instructions on creating and managing API keys in your SQLite database.

---

Session Tokens (Browser / Player)

If you are building a browser-based player or client-side application, use session tokens. Your API key never leaves the browser — your server calls POST /api/auth with a valid API key to receive a short-lived token, then sends that token down to the client for use on subsequent requests.

Step 1 — Get a token (server-side)

const { token } = await fetch('http://localhost:7860/api/auth', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(r => r.json());

POST /api/auth requires a valid API key from your self-hosted instance. The token inherits the tier of the key used to obtain it — a public key issues a public-tier token, a standard key issues a standard-tier token, and so on.

Step 2 — Send the token (client-side)

const res = await fetch('http://localhost:7860/movie?id=550', {
  headers: { 'X-Session-Token': token }
});

Tokens are HMAC-signed and verified server-side without shared in-memory state, so they work correctly across all server workers. Tokens expire after 30 minutes. Before they expire, refresh them with POST /api/auth/refresh instead of re-issuing from /api/auth — this avoids sending your API key to the browser again.

Step 3 — Refresh the token (client-side)

const res = await fetch('http://localhost:7860/api/auth/refresh', {
  method: 'POST',
  headers: { 'X-Session-Token': token }
});
const { token: newToken } = await res.json();

Tokens can be refreshed up to 10 minutes after they expire. Refresh preserves the tier of the original token. If the API key used to issue the token has since been disabled or changed tier, refresh will fail and you must re-authenticate via /api/auth.

Token errors

Error	Cause
Missing API key	POST /api/auth was called without a valid API key.
Invalid or expired session token	Token is malformed, tampered with, or older than 30 minutes. Re-fetch from /api/auth and retry.
Access denied	Token was issued from a public-tier key and was used to access a proxied stream.
Session token cannot be refreshed	Token is malformed, more than 10 minutes past expiry, or its source API key was disabled/changed. Re-fetch from /api/auth.

---

API Keys (Server-Side / Direct Access)

API keys are for server-side integrations and direct API access where the key is never exposed to end users.

Rate limits are enforced per API key — not per IP address or per user. Each request made with the same key counts toward that key’s limit regardless of where it originates.

Tier	Rate Limit	Streaming access
public	10 req / 60s	No
standard	100 req / 60s	Yes
partner	1000 req / 60s	Yes

When you self-host Vyla API, a default public key is automatically created:

public_api_key

This key has a rate limit of 10 requests per minute and can only access non-streaming endpoints (/api/health, /api/subtitles, /api/downloads).

The public tier cannot access the stream proxy (/api?url=...) or stream any video data. This restriction applies whether authenticating with a public API key directly or with a session token obtained from a public key. Streaming requires a standard or partner key, or a session token obtained from one.

You must create your own standard or partner API keys by inserting them directly into your SQLite database. See Self-Hosting for the SQL commands to add new keys.

Sending your key

Authorization Header

curl "http://localhost:7860/api/health" \
  -H "Authorization: Bearer YOUR_API_KEY"

API key errors

Error	Cause
Missing API key	No Authorization, X-API-Key, or X-Session-Token header sent.
Invalid API key	Key doesn’t match any known key in your database.
Rate limit exceeded	The key’s request limit has been hit for the current 60-second window.
Access denied	A public-tier key or token was used to access a proxied stream endpoint.

---

Rate Limiting

Rate limits are tracked per API key. Session token requests (authenticated via X-Session-Token) are not subject to rate limiting — only direct API key usage is counted.

When a limit is exceeded the API returns 429 with a JSON body:

{
  "error": "Rate limit exceeded",
  "resetAt": 1718000000000,
  "limit": 100,
  "window": 60000
}

resetAt is a Unix timestamp in milliseconds indicating when the window resets.

---

Which method should I use?

Use session tokens if your code runs in a browser. Putting an API key in client-side JavaScript exposes it in network requests — session tokens exist to prevent that. Your server fetches the token using its API key and passes it to the client.

Use API keys if your code runs on a server where the key is never sent to the browser.

---

Public vs. Protected Routes

Route	Auth required	public key/token allowed
GET /	No	Yes
POST /api/auth	Yes	Yes
GET /api/health	Yes	Yes
GET /api/subtitles/*	Yes	Yes
GET /api/downloads/*	Yes	Yes
GET /movie	Yes	No
GET /tv	Yes	No
GET /api/test/:id	Yes	Yes
GET /api/debug/:id	Yes	Yes
POST /api/auth/refresh	Yes (session token)	Yes
GET /api?url=	Yes	No