# 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.

## OAuth 2.0 for agents

Alongside API keys, `/api/v1` accepts OAuth 2.0 bearer tokens. This is the agent-native path: a client can discover everything, register itself and obtain scoped tokens without a human copying a key - only the consent screen needs a person.

Discovery starts at the standard metadata documents:

- `GET /.well-known/oauth-authorization-server` - RFC 8414 authorization server metadata (endpoints, grant types, `code_challenge_methods_supported`)
- `GET /.well-known/oauth-protected-resource` - RFC 9728 resource metadata (`scopes_supported` with descriptions)

The flow is authorization code with PKCE (S256 required), with dynamic client registration (RFC 7591):

1. `POST /api/oauth2/register` with `{ "client_name": "...", "redirect_uris": ["https://..."] }`. Clients are public by default; PKCE stands in for a secret. Loopback `http://localhost` redirect URIs are allowed for CLI and desktop agents.
2. Send the user to `/oauth2/authorize?response_type=code&client_id=...&redirect_uri=...&scope=videos:read videos:write&state=...&code_challenge=...&code_challenge_method=S256`. They pick a team and approve the scopes on the consent screen.
3. Exchange the code at `POST /api/oauth2/token` (`grant_type=authorization_code`, with your `code_verifier`).
4. Call the API with `Authorization: Bearer fl_oat_...` - exactly where an API key would go, with the scopes the user approved.

Access tokens live 1 hour; refresh tokens live 30 days and rotate on every use (`grant_type=refresh_token`). Reusing a rotated refresh token revokes the whole grant, so store the newest pair only. Revoke at `POST /api/oauth2/revoke`. Omitting `scope` grants read-only scopes; request write scopes explicitly.

API keys remain the simpler path for your own integrations: one header, no flow, no expiry. OAuth exists for clients acting on behalf of someone else's account.

Using the `faceless` CLI or the `faceless-mcp` stdio server? `faceless login` runs this whole flow for you - it opens the consent screen in your browser, stores the tokens in `~/.faceless/config.json`, and refreshes them automatically. No key to paste.

One disambiguation: elsewhere in these docs, "connecting" a platform refers to linking a **social account** (YouTube, TikTok, Instagram, X, Facebook, LinkedIn, Threads) to a team so the API can publish to it. That linking happens in the dashboard, in a browser, because each platform requires a human to grant consent on its own consent screen. `GET /accounts` then lists what is connected, and you pass those ids as `authId` when publishing.

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