> ## Documentation Index
> Fetch the complete documentation index at: https://docs.indigenius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate every request with your developer API key.

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

<CodeGroup>
  ```bash Bash theme={null}
  curl https://api.indigenius.ai/v1/auth/keys \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  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());
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

## 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](/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.