Authentication
Every request to /api/v1 must carry an API key. Keys belong to a registered developer, are tied to a plan, and can be revoked at any time from Developer settings.
Three ways to send the key
Authorization headerRecommended
curl -H "Authorization: Bearer xtvdb_YOUR_KEY" \ "https://xtvdb.com/api/v1/titles/XS1TV"
X-API-Key header
curl -H "X-API-Key: xtvdb_YOUR_KEY" \ "https://xtvdb.com/api/v1/titles/XS1TV"
Query parameter
https://xtvdb.com/api/v1/titles/XS1TV?api_key=xtvdb_YOUR_KEY
Convenient for quick tests, but query strings end up in logs and browser histories — prefer a header in anything real.
Keep your key secret
- The full key is shown once, at creation. We store only a hash — if you lose it, revoke it and create a new one.
- Never ship a key inside client-side code (browser bundles, mobile apps someone can decompile). Call the API from your backend.
- Use separate keys per environment (production, staging) so revoking one never takes the other down.
- Revocation is immediate — a revoked key fails on the next request.
Authentication errors
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No key found in the request. |
| 401 | invalid_api_key | The key is unknown, revoked, or the developer account is suspended. |
Check what a key resolves to at any time with GET /api/v1/me.