Authentication

Every request to the MAIA public API is authorized with an API key. API base URL: https://api.maia-ai.com.

Creating a key

Sign in to the dashboard at dashboard.maia-ai.com.
Open the “API and MCP” section → “API” tab.
Click “Create key”.
Copy the key and store it somewhere safe.

⚠️

The key is shown only once — right after it is created. If you lose it, the value cannot be recovered: revoke the old key and create a new one.

Every key starts with the maia_ prefix.

Scopes

When you create a key, you choose its access rights:

Scope	What it grants
`read`	Read data: list of projects, call history, call details, contacts
`write`	Write and trigger actions: place outbound calls

A key can have both scopes or just one. Placing calls (POST /v1/public/calls) requires the write scope. Read requests require read.

Passing the key

There are two equivalent ways to pass the key in an HTTP header. Use either one.

X-API-Key header

GET /v1/public/projects HTTP/1.1
Host: api.maia-ai.com
X-API-Key: maia_YOUR_KEY

curl https://api.maia-ai.com/v1/public/projects \
  -H "X-API-Key: maia_YOUR_KEY"

Authorization: Bearer header

GET /v1/public/projects HTTP/1.1
Host: api.maia-ai.com
Authorization: Bearer maia_YOUR_KEY

curl https://api.maia-ai.com/v1/public/projects \
  -H "Authorization: Bearer maia_YOUR_KEY"

Revoking a key

If a key is no longer needed or has been compromised, revoke it in the dashboard: “API and MCP” → “API” tab → find the key → “Revoke”. After revocation, any request with that key will return 401. Create a replacement key if needed.

Security

⚠️

An API key is a secret equivalent to a password. Anyone holding the key acts on your behalf and spends your balance.

Never publish a key in public repositories, frontend code, logs, or screenshots.
Store keys in environment variables or a secrets manager, not in source code.
For integrations that only need to read data, issue a key with the read scope only — without write. That way, a leak of such a key cannot place calls or spend your balance.
Use separate keys for separate integrations — if one is compromised, you can revoke it without affecting the others.
At any sign of a leak, revoke the key immediately and create a new one.

Error codes

Code	Reason
`401`	Key missing or invalid (including a revoked key)
`403`	The key lacks the required scope (e.g. `write` to place a call)