Authentication

API key authentication

The Indigenius Developer API uses static API keys passed in a request header. There are no OAuth flows or session tokens. Send your key in the X-API-Key header on every request:

curl https://api.indigenius.ai/v1/auth/keys \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch('https://api.indigenius.ai/v1/auth/keys', {
  headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
});
console.log(await response.json());

import requests, os

response = requests.get(
    "https://api.indigenius.ai/v1/auth/keys",
    headers={"X-API-Key": os.environ["INDIGENIUS_API_KEY"]},
    timeout=30,
)
print(response.json())

Key anatomy

When you create or list a key you’ll see two distinct identifiers:

Field	Description
`id`	The internal MongoDB ID of the key record. Used in management endpoints like `PATCH /v1/auth/keys/{id}/scopes`.
`publicKey`	A human-readable identifier prefixed `pk_live_`. Safe to log for traceability — it does not grant API access.

The actual secret used in X-API-Key is returned only at creation time. Store it immediately in a secret manager — it cannot be retrieved again. If it is lost, rotate the key.

Scopes

Every key is issued with a set of permission scopes. Calling an endpoint without the required scope returns 403 Forbidden. Scopes follow a resource:action pattern:

calls:read    calls:write
agents:read    agents:write
widgets:read    widgets:write
workflows:read    workflows:write
phone:read    phone:write
create_studio:read    create_studio:write
analytics:read
billing:read
keys:read    keys:write
webhooks:read

You can inspect or update scopes at any time — see Auth & Keys.

Error responses

Situation	Status	How to fix
Missing `X-API-Key` header	`401`	Add the `X-API-Key` header
Invalid or revoked key	`401` / `404`	Verify the key value and status
Key lacks required scope	`403`	Add scope via `PATCH /v1/auth/keys/{id}/scopes`
Key expired	`401`	Create a new key or rotate

Best practices

Never expose keys client-side. API keys must only be used in server-side code or secure environments. Do not embed them in frontend JavaScript, mobile apps, or public repositories.
Use environment variables. Store keys as INDIGENIUS_API_KEY and read them at runtime — never hardcode them.
One key per environment. Create separate keys for dev, staging, and prod so a compromised key cannot affect all environments.
Least privilege. Grant only the scopes a key actually needs.
Rotate regularly. Use POST /v1/auth/keys/{id}/rotate on a schedule and immediately after any suspected exposure.

Getting Started

Core APIs

Platform APIs

API key authentication

Key anatomy

Scopes

Error responses

Best practices

​API key authentication

​Key anatomy

​Scopes

​Error responses

​Best practices

API key authentication

Key anatomy

Scopes

Error responses

Best practices