> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/api-and-webhooks/authentication.md).

# Authentication & API keys

Every API call authenticates with an **API key** passed as a bearer token:

```
Authorization: Bearer inpk_live_...
```

There are no OAuth flows or session cookies on the API: one key, one header. Dashboard features (building surveys, managing members, billing) are not reachable with an API key by design.

***

### Creating and managing keys

Keys live in the dashboard under **Integrations Hub → API Keys** (admin-only). Each key has:

* A **label**, so you can tell your CRM sync from your data-warehouse export.
* An **environment**: `inpk_live_*` for production traffic, `inpk_test_*` for staging integrations. They behave identically; the split exists so you can revoke staging without touching production.
* A **permission scope** (below).
* **Per-key usage statistics**, including real response status codes, so you can spot a failing integration from the dashboard.

The secret is shown **once** at creation. Store it like a password; rotate it from the same screen if it leaks or when a teammate with access leaves.

***

### Permission scopes

Scope what each integration can do; don't hand every system an `all` key.

| Scope      | What it allows                                                                                                                                                                     |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `push`     | Push feedback to existing sources, and everything push implies (bulk status, listing, analysis reads).                                                                             |
| `create`   | Everything `push` can, plus creating feedback groups, sources, and fields.                                                                                                         |
| `send`     | Trigger survey-invite emails ([Sending invites](/boundaryai-docs/api-and-webhooks/sending-invites.md)). Deliberately separate: emailing humans is a bigger deal than pushing data. |
| `mcp_read` | Read-only access for the MCP endpoint, so an AI assistant can query analytics but never write. See [Connect AI assistants](/boundaryai-docs/api-and-webhooks/mcp.md).              |
| `all`      | Everything above.                                                                                                                                                                  |

{% hint style="info" %}
`send` is additionally gated on a **verified sending domain**: API sends never ride the shared BAI Analytics sender, so automated volume runs on your own sending reputation. See [Sending invites](/boundaryai-docs/bringing-in-your-feedback/surveys/managing-surveys.md#sending-invites-share-send).
{% endhint %}

***

### Introspection: `GET /me`

An integration can discover its own capabilities without dashboard access:

```bash
curl https://app.boundary-ai.com/api/input/me \
  -H "Authorization: Bearer $BAI_API_KEY"
```

The response includes the key's name, environment, and permissions, the **effective rate limits**, the organisation's credit status, and the **webhook event types** available for subscription. It charges nothing, which also makes it the right target for connection tests (it's what Zapier's *Test Connection* step calls).

***

### Rate limits

Defaults: **60 requests/minute per key** and **1,000 requests/minute per organisation**, on a 60-second window. Your key's exact numbers are in `GET /me`; higher per-key limits can be set when a key is created.

When you hit a limit the API returns **429** with a `Retry-After` header. Back off and retry; for sustained volume, prefer the bulk endpoints (one call for thousands of items) over per-item calls.

***

### Good practices

* **One key per integration.** Revoking a compromised system shouldn't take down the others.
* **Scope down.** A CRM sync needs `push`, not `all`.
* **Use `Idempotency-Key` on writes.** Any push can be retried safely within 24 hours.
* **Rotate on staff changes.** Same policy as passwords.