Authentication

One header, two kinds of token. Which one you want depends on whose account the work belongs to.

Every request carries Authorization: Bearer <token>. There is no query-parameter form and no cookie form — the API is called from your server, and a token in a URL ends up in access logs.

Use	Token	Whose account
API key server to server	`vmk_live_…` / `vmk_test_…`	Yours. Every byte generated bills you.
OAuth access token acting for a user	64 hex characters	The user who granted consent.

API keys

Mint one in Apps. The plaintext is shown once and never again — only a SHA-256 hash is stored, so a leak is fixed by revoking and minting, not by looking it up.

curl https://api.vidmoat.com/v1/me \
  -H "Authorization: Bearer $VIDMOAT_KEY"

The prefix is load-bearing. vmk_test_ and vmk_live_ make the environment legible in a log line or a screenshot without a database lookup — so a test key pasted into production config is obvious at a glance. Keys minted before the developer platform have no environment segment and keep working unchanged.

Test keys never spend and never render. Wire the whole integration up on a test key, on any plan, for free. A live key needs the Studio plan, because a live key can spend real credits.

A key can never manage keys. Every route under /api/developer rejects API-key auth outright. If a key could mint a key, it could grant itself a scope it does not have, and the scope ceiling would be decoration.

Sign in with Vidmoat (OAuth 2.0 + PKCE)

When your product edits your user’s videos rather than your own, you want an access token for them, not your key. Vidmoat speaks OAuth 2.0 authorization code with PKCE S256, plus RFC 7591 dynamic client registration, at https://api.vidmoat.com/api/oauth. Discovery metadata is where you expect it:

curl https://api.vidmoat.com/.well-known/oauth-authorization-server

The flow is /authorize → user consents → code → /token → access + refresh token. Both client_secret_post and client_secret_basic are accepted. Redirect URIs are allowlisted per client and support an https://prefix* form, because some connector platforms mint a fresh callback per install.

Scoped consent is being built right now. The protocol layer has been in production for a while serving MCP clients, where consent is a single Allow/Deny with no scope display — because until this release there were no scopes. Third-party OAuth with a scoped consent screen, per-user grants and short-lived access tokens is Phase 3 and is in flight. Until it lands, use an API key on your own account, and design your token storage as if the token were short-lived and rotating, because it will be.

What the credential does not change

A token identifies a real Vidmoat user, always. There are no anonymous sub-identities, and that is deliberate: every generated frame is attributable to an account with a monitored contact address, which is what makes moderation and takedown possible at all. Plan limits, credit balance, export quota and content moderation apply to the token’s owner exactly as they do in the editor.

So a scope is necessary but never sufficient. A key carrying ai.video on a Creator-plan account still returns 402, because the plan does not include video generation. Read scopes next.

Versioning. Additive changes ship into v1 — new fields, new endpoints, new enum values. Ignore unknown fields; a client that rejects them will break on a routine release. Breaking changes get a /v2, and v1 is supported for at least 12 months after one exists. Send Vidmoat-Version: 2026-08-01 to pin date-based behaviour within v1.