# BlitzReels Authentication

Use this document to authenticate agents, scripts, SDKs, CLI clients, and MCP clients with BlitzReels.

## Pick a method

### Supported authentication methods

- **REST API:** API key sent as a Bearer token; the `X-BlitzReels-Workspace` header names the workspace.
- **MCP server:** OAuth 2.1 discovery and authorization for clients that support remote MCP authentication.
- **Dashboard:** browser session authentication. Dashboard cookies are not API credentials.

## Register

For REST access, create a BlitzReels account at https://blitzreels.com/register, then create a key in **Dashboard → Workspace → AI → API Keys**. Only workspace owners and admins can create keys. The full key is shown once and inherits the workspace plan limits.

For MCP OAuth clients that support dynamic client registration, use the registration endpoint advertised by authorization-server metadata: https://blitzreels.com/api/oauth/register.

## Discover

The canonical remote MCP endpoint is https://blitzreels.com/api/mcp. Discover its OAuth protected-resource metadata at https://blitzreels.com/.well-known/oauth-protected-resource/api/mcp and its authorization-server metadata at https://blitzreels.com/.well-known/oauth-authorization-server. Follow the advertised endpoints and PKCE methods rather than guessing URLs.

## Claim

A REST API key belongs to a user and carries that user's current role in the target workspace. An account key reaches every workspace its owner belongs to; a workspace key reaches only its own. MCP OAuth clients request the scopes advertised by authorization-server metadata, including `openid`, `profile`, `email`, and `offline_access` when refresh access is needed. Do not request permissions the workflow does not use.

## Use credential

### REST API keys

Send the key as a Bearer token in every protected REST request. Name the workspace with `X-BlitzReels-Workspace`; without it, a workspace key acts in its own workspace and an account key in its owner's default workspace. `GET /api/v1/workspaces` lists the workspaces a key can reach.

```http
Authorization: Bearer $BLITZREELS_API_KEY
X-BlitzReels-Workspace: WORKSPACE_ID
```

Validate a key before debugging project IDs or endpoint paths:

```bash
curl https://blitzreels.com/api/v1/auth/validate \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

A successful validation response identifies the workspace (`organization_id`, `workspace_name`), the user's `role` there, the `key_scope` (`account` or `workspace`), environment, plan, key prefix, and current agent-skill guidance.

### MCP OAuth 2.1

The canonical remote MCP endpoint is:

- https://blitzreels.com/api/mcp

Discover its OAuth protected-resource metadata here:

- https://blitzreels.com/.well-known/oauth-protected-resource/api/mcp

Authorization server metadata is available here:

- https://blitzreels.com/.well-known/oauth-authorization-server

MCP clients should follow the advertised metadata rather than guessing authorization or token endpoints. The compatibility Server Card is available at https://blitzreels.com/.well-known/mcp/server-card.json.

## Authentication errors

- **401 Unauthorized:** the Bearer credential is missing, malformed, invalid, expired, or revoked.
- **403 Forbidden:** the credential is valid but the user or workspace lacks permission for the operation. Workspace refusals use `error_code: "permission_denied"` with `error_details.reason`: `workspace_forbidden` (unknown workspace or not a member), `workspace_restricted` (a workspace key named another workspace), `workspace_required` (no default workspace; send the header) or `role_cannot_write` (viewer role on a non-GET request).
- **404 Not Found:** `hint` names the workspace the request looked in; the resource may live in another workspace.
- **authentication_error:** the REST API could not authenticate the supplied API key.

On 401, stop and request a valid credential. Do not retry the same rejected token. On 403, do not change or bypass workspace permissions.

## Revocation

Revoke a REST API key from **Dashboard → Workspace → AI → API Keys**, then replace it in the integration's secret store. A revoked key must not be retried. To remove MCP OAuth access, disconnect the BlitzReels integration in the MCP client and complete authorization again if access is needed later.

## Credential safety

- Never put API keys or OAuth tokens in URLs, query strings, source control, logs, or chat messages.
- Store credentials in a secret manager or protected environment variable.
- Restrict a key to one workspace when an integration needs only that workspace.
- Rotate a key immediately if it is exposed.
- Do not use browser session cookies as API credentials.

## Related resources

- [Authentication guide](https://blitzreels.com/docs/authentication.md)
- [API index](https://blitzreels.com/api/llms.txt)
- [OpenAPI specification](https://blitzreels.com/api/openapi.json)
