Authentication

This page is the contract: what the header looks like, what each credential reaches, and what comes back when it cannot. Creating, rotating, and capping keys is on authentication.

The header

Every authenticated request sends exactly one bearer token:

Authorization: Bearer <credential>

The scheme is case-insensitive. The value must be the scheme, whitespace, and the token, with nothing after it. Anything else counts as no credential. There is no query parameter, no X-API-Key header, and no Basic auth.

The API decides what the token is from its prefix:

A key pasted without its mak_ prefix is checked as an OAuth token and fails with 401 unauthorized, with a message that API keys start with mak_. Send the key exactly as it was shown.

Credentials

Scope per endpoint

An API key needs one of the scopes listed for the endpoint. OAuth sessions pass every scope check.

A key without the scope gets 403, and the body says what was missing:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the `manage` scope. This key has: generate. Add the scope to this key in the dashboard, or use a key that has it.",
    "scopes": { "required": ["manage"], "current": ["generate"] }
  }
}

Read error.scopes.required rather than parsing message. Scopes can be changed on an existing key in the dashboard, or with PUT /api-keys/{id}.

Which tasks a key can read

• GET /tasks lists only the tasks the calling key created. An OAuth session lists every task on the account.
• GET /tasks/{id}, /status, and /result check the account, not the key. Any key on your account with generate can read any of your tasks by id.
• Another account's task answers 404 task_not_found, never 403, so the API never confirms that an id exists.

Public access tokens

POST /image/generate, POST /image/remove-background, POST /image/upscale, and POST /video/generate return a token for the task they create when the body asks for one with "generate_public_access_token": true:

{
  "data": {
    "task_id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "estimated_cost": "0.03",
    "public_access_token": "pat_eyJhbGciOiJIUzI1NiJ9..."
  }
}

• It works as a bearer token on GET /tasks/{id}/status and GET /tasks/{id}/result for that task. Every other endpoint rejects it.
• It expires one hour after it is issued, and nothing refreshes it.
• Without generate_public_access_token: true there is no token. Ask for one only when browser code will poll the task.
• If the task is created but its token cannot be generated, the create answers 500 public_access_token_failed with the task's id in error.task_id. The task runs: follow it from your server rather than resending, which would create and charge a second task.
• POST /image/rate, /image/alt, and /image/review never return one.

Poll for results has the pattern end to end.

CORS

The allowed request headers are Authorization and Content-Type. Credentials mode is off, so cookies are never sent. A browser call to /image/generate from your own origin fails the preflight, whatever it sends.

Failures

A pat_ problem is never a 404 on those two paths. A malformed or expired token fails with its own 401 first.

Every code, with what to do about it, is on errors.

Next steps

• Authentication: create a key, set scopes, rotate, cap spending.
• The task object: what the task endpoints return.
• Errors: every code the API can send.