Authentication

Every request to https://faceless.so/api/v1 is authenticated with an API key. Keys are created in the dashboard, in your team settings at https://faceless.so/team, and look like fl_live_....

Sending the key

Two headers are accepted; use whichever fits your HTTP client:

bash 
curl -s https://faceless.so/api/v1/me \
  -H "Authorization: Bearer $FACELESS_API_KEY"
bash 
curl -s https://faceless.so/api/v1/me \
  -H "X-API-Key: $FACELESS_API_KEY"

Keys are accepted in headers only. Never put a key in a URL or query string; URLs end up in logs.

A missing or invalid key returns 401 with error type unauthorized.

Scopes

Each key carries a set of scopes chosen at creation. Calling an endpoint the key is not scoped for returns 403 with error type forbidden_scope.

  • credits:read: credit balance and ledger (GET /credits)
  • videos:read: list and read videos, poll generation status and renders (GET /videos, GET /videos/{id}, GET /videos/{id}/status, GET /renders/{id})
  • videos:write: create, caption, update, render and delete videos (POST /videos, POST /videos/captions, PATCH /videos/{id}, POST /videos/{id}/render, DELETE /videos/{id})
  • series:read: list and read series and their episodes (GET /series, GET /series/{id}, GET /series/{id}/episodes)
  • series:write: create, update and delete series, force the next episode (POST /series, PATCH /series/{id}, DELETE /series/{id}, POST /series/{id}/generate)
  • posts:read: the posting calendar (GET /calendar)
  • posts:write: publish, schedule and cancel posts (POST /posts, POST /posts/schedule, DELETE /posts/{id})
  • accounts:read: list connected social accounts (GET /accounts)
  • assets:read / assets:write: read and register media assets (POST /assets)
  • analytics:read: cross-platform performance (GET /analytics)
  • catalog:read: voices and option catalogs (GET /voices, GET /options)

GET /me works with any valid key regardless of scopes; use it to check which scopes a key has (data.auth.scopes).

Legacy team keys

Teams created before scoped keys have a legacy team API key (a UUID). It still works in the same headers and is treated as having every scope. Prefer creating a scoped fl_live_ key: it can be revoked on its own and limits the blast radius of a leak. GET /me reports data.auth.legacy: true when a legacy key is used.

Managing keys

Everything happens in team settings at https://faceless.so/team:

  • Create a key with a name and the scopes it needs
  • The full key is shown once, at creation; only a prefix (like fl_live_a1b2c3d4) is visible afterwards
  • Revoke a key at any time; revoked keys stop working immediately

Security notes

  • Store keys in environment variables or a secret manager, never in source control
  • Give each integration its own key with the minimum scopes it needs, so one leak has a small blast radius and revocation does not break everything else
  • If a key leaks, revoke it in the dashboard and create a new one
  • Keys act on behalf of your team; treat them like passwords