Authentication

How Fotovid API keys work — format, the Authorization header, scopes, expiry, and rotation.

Every request to the Fotovid API is authenticated with an API key sent as a Bearer token. Keys are created and managed in the web dashboard.

The Authorization header

Send your key in the Authorization header on every request:

Authorization: Bearer p6_<key_id>:<secret>

There is no X-API-Key header — Bearer is the only scheme.

Key format

A full key looks like p6_<key_id>:<secret>:

Part	Example	Notes
Prefix	`p6_`	Identifies a Fotovid key. Not secret.
Key ID	`01JGXYZ1ABCD...`	A 26-character ULID. Safe to log; it's how a key is identified in the dashboard.
Secret	`a1b2…` (64 hex)	256 bits of randomness. This is the sensitive part — treat it like a password.

Create and manage keys

Create keys in the dashboard under Account → API Keys. A default key is created for you when you sign up.

The full key — including the secret — is shown only once, at creation. Copy it immediately and store it in a secret manager. List and detail views only ever show a masked prefix like p6_01JGXYZ1...; the secret is never recoverable afterward. Lost it? Create a new key and revoke the old one.

Fotovid never stores your secret in plaintext — only a SHA‑256 hash of it — so support cannot recover a lost key either.

Which auth does each endpoint use?

The public media API accepts your API key:

Tasks — POST /v1/tasks, GET /v1/tasks, GET /v1/tasks/{id}, POST /v1/tasks/{id}/cancel
Synchronous — POST /v1/image/watermark, POST /v1/video/watermark, POST /v1/video/extract-cover, POST /v1/video/trim, POST /v1/audio/trim, POST /v1/video/extract-audio, POST /v1/video/probe

Account-management actions (creating keys, rotating your webhook secret) are done in the dashboard and are not part of the API-key surface.

Scopes

Keys carry coarse-grained scopes, both granted by default:

read — GET requests
write — POST / PUT / DELETE requests

Expiry and rotation

Expiry — optional, 1–365 days. By default a key never expires.
Rate limit — each key has a per-key request-rate limit (60 requests/min by default). See Rate limits.
Revoke — revoking a key in the dashboard disables it immediately and is permanent (the record is kept for audit). To rotate, create a new key, deploy it, then revoke the old one.

Errors

A bad, missing, revoked, or expired key returns 401 with a generic message (the API does not reveal which of those it was):

{
  "type": "https://api.fotovid.co/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "AUTH_INVALID_TOKEN"
}

Exceeding a key's rate limit returns 429 (RATE_LIMIT_EXCEEDED). See Errors for the full contract.