Where do I get a MakeAIVideo API key?

Create one in the app under Settings, Advanced, API keys. Keys are prefixed mav_ and belong to an organization rather than a person, so anyone in that workspace acts through the same key.

What is the difference between the read, write and ai scopes?

read lists and inspects, write creates and edits and is the scope that spends credits, and ai covers the generation helpers such as scripts, ideas and voice previews. A key can hold any combination.

Why am I getting a 403 from the API?

The key is valid but lacks the scope that endpoint requires. Every operation lists its scope in the reference; reissue the key with that scope, because retrying the same request will keep failing.

Can I see an API key again after creating it?

No. A key is shown once, at creation, and cannot be retrieved afterwards. Store it in a secret manager or your keychain at that moment, and issue a new key if you lose it.

How do I authenticate a machine with no browser?

Use the device-code flow. POST /auth/device returns a short code the user approves in a browser elsewhere, then your client polls POST /auth/device/token to receive the key.

Authentication

Every endpoint except the device-login pair takes an organization API key as a bearer token.

Keys

Create a key in the app under Settings, Advanced, API keys, or with the CLI device flow. Keys are prefixed mav_ and belong to an organization, not a user.

Header

Authorization: Bearer mav_...

curl

curl https://app.makeaivideo.ai/api/v1/me \
  -H "Authorization: Bearer $MAV_API_KEY"

A key is shown once, when it is created. Store it somewhere durable at that moment; we cannot show it again.

Scopes

Every key carries scopes, and every operation declares the one it needs. The scope is listed on each endpoint in the reference.

Scope	Covers
read	Lists and inspects. Fetching videos, characters, webhooks, credits.
write	Creates, edits, regenerates and deletes. This is the scope that spends credits.
ai	Generation helpers: scripts, ideas, portraits, voice previews, music.

Scope keys down to what the integration actually needs. A read-only reporting job should not hold a key that can spend credits.

When a scope is missing

A key without the required scope gets 403 forbidden. This is not retryable; reissue the key with the scope it needs.

403

{
  "data": null,
  "error": {
    "message": "Missing required scope: write",
    "code": "forbidden",
    "retryable": false
  },
  "meta": { ... }
}

A missing or malformed token returns 401 instead. Both are 4xx, so retryable is false: retrying the identical request will fail identically.

Device-code login

For terminals and machines without a browser, the API implements device-code flow (RFC 8628) across POST /auth/device and POST /auth/device/token. These two are the only unauthenticated endpoints. Start a login, show the user the code, then poll for the token; the key is returned once, on success. See the Auth reference and the CLI page.

Authentication questions

Where do I get a MakeAIVideo API key?: Create one in the app under Settings, Advanced, API keys. Keys are prefixed mav_ and belong to an organization rather than a person, so anyone in that workspace acts through the same key.
What is the difference between the read, write and ai scopes?: read lists and inspects, write creates and edits and is the scope that spends credits, and ai covers the generation helpers such as scripts, ideas and voice previews. A key can hold any combination.
Why am I getting a 403 from the API?: The key is valid but lacks the scope that endpoint requires. Every operation lists its scope in the reference; reissue the key with that scope, because retrying the same request will keep failing.
Can I see an API key again after creating it?: No. A key is shown once, at creation, and cannot be retrieved afterwards. Store it in a secret manager or your keychain at that moment, and issue a new key if you lose it.
How do I authenticate a machine with no browser?: Use the device-code flow. POST /auth/device returns a short code the user approves in a browser elsewhere, then your client polls POST /auth/device/token to receive the key.