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. 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:

{
  "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 scopes.required rather than parsing message. Scopes can be changed on an existing key in the dashboard, or with PUT /api-key/{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, and POST /video/generate return a token for the task they create:

{
  "data": {
    "taskId": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "estimatedCost": "0.03",
    "access": { "publicAccessToken": "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.
• Send "access": { "pat": { "enabled": false } } in the create body to skip it.
• Treat data.access as optional even when enabled. If signing fails, the task is still created and the field is missing.
• 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.