Motionpit
Sign inGet started

Authentication

API keys

VideoAI API keys authenticate backend-to-backend requests. Each key is scoped to one organization.

Create a key

Go to Settings → API Keys. Click Create key, give it a name, and copy the full key immediately — it is shown only once. The server stores a hashed version; you cannot recover the plaintext later.

Header format

Include the key in every request using the Authorization header:

Authorization: Bearer vam_live_<key>

Example:

curl https://your-domain.com/api/v1/formats \
  -H "Authorization: Bearer vam_live_abc123..."

Scope

Keys are per-organization. A key issued by one org cannot access resources belonging to another org. Members of the same org share the same resource space, so treat org-level keys like shared credentials.

Security recommendations

  • Never commit keys to source control. Use environment variables (API_KEY=vam_live_...) or a secrets manager.
  • Rotate keys regularly. Go to Settings → API Keys → Rotate next to the key. The old key is revoked immediately.
  • Revoke immediately if leaked. Use Settings → API Keys → Revoke. A revoked key returns 401 invalid_api_key on all subsequent requests.
  • Name keys by usage context (e.g. ci-deploy, production-backend) so you can revoke the right one without disrupting others.

Session authentication (UI-only routes)

The browser dashboard uses session cookies set by Better-Auth after sign-in. A small set of routes — notably /v1/user-blocks/ai/chat — are session-only and reject API keys. These routes are marked with a session_auth_required tag in the API reference. They are not intended for programmatic use.

Deprecation policy

Breaking changes come with a 30-day notice via email to the org owner and an X-Deprecated: true response header on affected endpoints. Non-breaking additions (new fields, new endpoints) are made without notice.