Skip to content

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. A missing, unknown, revoked or expired token gets 401 unauthorized with a WWW-Authenticate: Bearer realm="vidmoat", resource_metadata="..." header naming the RFC 9728 metadata document, which leads to the OAuth endpoints below. Agents can read all of this as Markdown at https://api.vidmoat.com/auth.md.

UseTokenWhose account
API key, server to servervmk_live_… or vmk_test_…Yours. Everything it generates bills you.
OAuth access token, acting for a user64 hex charactersThe user who granted consent. Always live.

API keys#

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

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

Test and live#

  • Test keys are free on every plan. They never spend credits and never queue a real render, but projects and edits they make are real. See test and live keys.
  • Live keys need three things: the developer agreement accepted, the app approved in review, and a plan with live API access (Studio, Team or Enterprise). A live key can spend real credits.

Sign in with Vidmoat (OAuth 2.0)#

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, plus RFC 7591 dynamic client registration. Discovery metadata is where you expect it:

Shell
curl https://api.vidmoat.com/.well-known/oauth-authorization-server
StepEndpoint
Authorize (the user consents here)https://www.vidmoat.com/oauth/authorize
Exchange the code, refresh a tokenPOST https://api.vidmoat.com/api/oauth/token
Register a client dynamicallyPOST https://api.vidmoat.com/api/oauth/register (10 an hour per IP)
  • Grants: authorization_code and refresh_token. Client authentication: client_secret_post or client_secret_basic.
  • Use PKCE with S256. (plain is accepted for older MCP clients; do not choose it.)
  • Redirect URIs are allowlisted per client and support an https://prefix* form, because some connector platforms mint a fresh callback per install.
  • The consent screen lists the scopes you ask for, with the ones that can spend credits flagged, using the same descriptions as the scope reference.
  • For a client that belongs to a developer app, access tokens last 1 hour and refresh tokens 90 days, rotating on every use. Store the newest refresh token each time.
  • Users can see and revoke every connection at https://www.vidmoat.com/oauth/connected: your app under its name, and dynamically registered clients (MCP assistants) as assistant connections, by the name they registered. Revoking deletes every access and refresh token for that connection, and the next call fails with 401.
  • OAuth tokens are clamped to the scopes the user consented to and to your app's scope ceiling.

Your app's OAuth client#

Open your app in Apps and choose the OAuth tab to create its client. You get a client id (vma_…) and a client secret (vmcs_…).

  • The secret is shown once. Only a hash is stored. Rotating it gives you a new one and the old one stops working at the token endpoint straight away; tokens people already hold keep working, and refreshing them needs the new secret.
  • Redirect URIs follow the same rule as dynamic registration: https, or http only on localhost or 127.0.0.1, no fragment, no user name or password, and an optional trailing * for a prefix. A request naming any other address is refused before the consent screen.
  • What your app may ask for is a list you choose, inside the limit Vidmoat sets for the app. A request for more is trimmed to it before the person sees the consent screen, and the token endpoint refuses a code or a refresh that carries a scope you have since removed (invalid_scope: send the person through sign-in again).
  • Turning the client off refuses sign-ins, code exchanges and refreshes, and stops tokens already issued, until you turn it back on. Deleting it signs out everyone who signed in with it.
  • Until your app is approved in review, only you can sign in to it, so you can build and test with your own account.
  • The consent screen shows your app's name and the logo you set on the OAuth tab.

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. Plan limits, credit balance, export allowance 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 plan without video generation still returns 402 plan_required. Read scopes next.

When a request is refused#

StatusCodeMeaning
401unauthorizedNo token, or one that is unknown, revoked or expired.
403insufficient_scopeThe token lacks a scope. The error names it (scope) and lists what you have (granted).
403access_suspendedThe owning account is restricted. restriction says what, until when and how to appeal.
403app_suspendedThe app's kill switch is on, independent of the account.