Skip to main content

​
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:
FieldDescription
idThe internal MongoDB ID of the key record. Used in management endpoints like PATCH /v1/auth/keys/{id}/scopes.
publicKeyA 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

SituationStatusHow to fix
Missing X-API-Key header401Add the X-API-Key header
Invalid or revoked key401 / 404Verify the key value and status
Key lacks required scope403Add scope via PATCH /v1/auth/keys/{id}/scopes
Key expired401Create 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.