Authentication

Most requests to the Vocal Video API carry a workspace API key as a bearer token — no sessions, no cookies. The same key works across the REST API and the MCP server. The MCP server also accepts OAuth 2.1 for hosted clients that connect from a URL — see OAuth for MCP clients.

API keys

Create and manage keys under Settings → API keys. A key is scoped to one workspace and acts as the user who created it. API access must be enabled for the account, or every call returns 403 api_disabled.

Authorization: Bearer <your-api-key>

Scopes

Each key has a scope that gates which tools it may call:

Scope	Can call
read	Read-only tools — the get_* and list_* tools.
write	Any tool, read or write.

A read-scoped key calling a write tool is rejected before the tool runs. Pick the narrowest scope that does the job: a key that only needs to pull replies or list storyboards should be read.

OAuth for MCP clients

Hosted MCP clients — like Claude custom connectors — can authenticate to the MCP server with OAuth 2.1 instead of a pasted key. You give the client the MCP endpoint URL; it discovers the authorization server, registers itself, and runs a standard PKCE authorization-code flow. You approve a consent screen once, and the client renews its own short-lived tokens after that. Scopes work exactly as above — the token is read or write, enforced per tool.

The REST API is API-key only; OAuth applies to the MCP server. The full flow — discovery documents, dynamic client registration, and the resource binding — is documented in the MCP reference.

Errors

Auth and validation failures come back as a consistent envelope with a stable code:

{ "error": { "code": "forbidden_scope", "message": "This API key has `read` scope; `create_storyboard` requires `write`." } }

Status	code	Meaning
401	unauthorized	Missing or invalid key.
403	api_disabled	API access isn't enabled for the account.
403	forbidden_scope	The key's scope is too low for this tool.
403	forbidden_role	The workspace access holding the key is reviewer-level and can't make editor changes.
400	invalid_input	Request body failed the tool's schema validation.
413	response_too_large	Result exceeded the size cap; narrow the query.
422	value_too_long	A text value exceeded the length its field allows.

Scope and role are separate gates. Scope is a property of the key; role is a property of the workspace access that minted it. A write key held by a reviewer still can't call an editor tool — and like every other refusal here, the status says so and nothing was written.

Irreversible tools need a confirmation token

A few tools send real email or spend credits — send_collector_invitation and share_draft_for_review. Because there's no human in the loop on the API, these use a two-step handshake instead of a self-asserted flag:

1. Call with confirm: false to get a preview plus a signed, content-bound confirmation_token.
2. Call again with confirm: true and echo that token to actually send.

The token is bound to the exact recipients and message in the preview and expires shortly, so a write key can't fire a blast on the first call, and a token issued for one preview can't authorize a different send. See each tool's entry in the API Reference for the precise fields.