Authentication

Send your developer key with every request; what each 401 means.

Every /v1 endpoint except GET /v1/openapi.json needs a developer key.

#Sending the key

Send the key in the Authorization header with the Key scheme:

HTTP

Authorization: Key aitk_live_...

The Bearer scheme is accepted too, so HTTP clients that only know bearer tokens work unchanged:

HTTP

Authorization: Bearer aitk_live_...

The scheme name is case-insensitive. Nothing else (query string, cookie, other headers) is read as the key.

#Keys

A key looks like aitk_live_ (live) or aitk_test_ (sandbox) followed by 43 letters and digits.
A live key works only on https://api-live.aitopia.ai, a test key only on https://api-sandbox.aitopia.ai; on the other server it is refused with 403 KEY_ENVIRONMENT_MISMATCH.
Create and revoke keys on aitopia.ai under profile menu > API keys. The key is shown once, when you create it; AITOPIA stores only a hash and a hint such as aitk_live_…abcd, so a lost key cannot be shown again: create a new one.
An account can have at most 10 active keys. Guest accounts cannot create keys.
A revoked key stops working immediately, on every server.
Each key also has a webhook secret, shown once at creation and rotatable later (see Webhooks).
A key may carry its own limits: a lower per-minute rate limit (Rate limits) and a monthly credit cap (Billing & retention).

Keep keys on your server. Anyone who has a key can spend the credits of the account that owns it.

#Identity

A key always acts as the AITOPIA user who created it: runs are billed to that account and results are saved to it. A key never falls back to another identity.

Requests belong to the account, not to a single key: any key of the same account and the same environment (live or sandbox) can read or cancel a request. A request_id of another account, or of the other environment, answers 404 NOT_FOUND.

A key is attached to the sign-in session of its owner on aitopia.ai. When you sign in to aitopia.ai, your current session is attached to all your active keys again. If that session has ended, calls answer:

JSON

{
  "error": {
    "code": "KEY_SESSION_EXPIRED",
    "message": "Sign in to aitopia.ai to reactivate this key.",
    "retryable": false
  }
}

Sign in to aitopia.ai with the account that owns the key; the key works again without any change on your side. Requests that were still running keep being tracked, and their results appear once the key works again.

#401 responses

Code	Message	Meaning
`UNAUTHENTICATED`	`Send your developer key as "Authorization: Key <key>".`	No `Authorization` header, or not in the `Key <key>` / `Bearer <key>` form.
`UNAUTHENTICATED`	`The developer key is invalid or has been revoked.`	Unknown, mistyped or revoked key.
`KEY_SESSION_EXPIRED`	`Sign in to aitopia.ai to reactivate this key.`	The key is valid but its owner's aitopia.ai session has ended.

A key sent to the wrong server answers 403 KEY_ENVIRONMENT_MISMATCH: test keys belong on the sandbox, live keys on the live server (Sandbox).

If the key cannot be checked because of a problem on our side, the answer is 500 INTERNAL_ERROR with retryable: true; retry after a short pause.

#Example

curl

curl "https://api-live.aitopia.ai/v1/account/balance" \
  -H "Authorization: Key $AITOPIA_KEY"

Node.js

const res = await fetch("https://api-live.aitopia.ai/v1/account/balance", {
  headers: { Authorization: `Key ${process.env.AITOPIA_KEY}` },
});
console.log(res.status, await res.json());

Python

import os, requests

r = requests.get(
    "https://api-live.aitopia.ai/v1/account/balance",
    headers={"Authorization": f"Key {os.environ['AITOPIA_KEY']}"},
)
print(r.status_code, r.json())