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

# Authentication

> The two headers every Bindbee API request carries, where to find them, and which endpoints need which.

Every request carries an API key. Requests that touch one customer's data carry a connector token as well.

| Header | Value | Identifies |
| - | - | - |
| `Authorization` | `Bearer <BINDBEE_API_KEY>` | Your organization |
| `X-Connector-Token` | `<CONNECTOR_TOKEN>` | One customer's connection |

## Where to find them

**API key** - Settings → [API Key](https://app.bindbee.dev/settings/keys). Each environment has its own, and a development key does not work against production data - see [Environments](/get-started/environments). Regenerating a key invalidates the old value immediately.

**Connector token** - it exists once the end user has authorized the connection. Where you read it depends on how they connected - see [How to connect](/get-started/how-to-connect).

* **Embedded Link** - `onSuccess` hands your frontend a short-lived `temporary_token`, which cannot read data. Swap it from your backend with the [token exchange](/sdk/get-connector-token).
* **Magic Link** - there is no temporary token. Look the connector up by the `origin_id` you set, with [Get Connectors](/api-reference/connectors/get-connectors).
* **Any route** - the connector's **Connector Details** panel in the dashboard, for a one-off lookup.

<Warning>
  A connector token is scoped to one API category. An HRIS token used against
  `/api/ats/v1/*` returns `403` even though both credentials are valid.
</Warning>

## Which endpoints need the connector token

The API key is required everywhere. The connector token is required only where the request names a customer.

| Endpoints | `X-Connector-Token` |
| - | - |
| Unified data (`/api/{category}/v1/*`), [passthrough](/api-reference/passthrough/make-passthrough-request), [resync](/api-reference/connectors/resync-connector) | **Required** |
| [Connectors](/api-reference/connectors/get-connectors), [integrations](/api-reference/integrations/get-integrations), [custom fields](/api-reference/custom-fields/list-custom-fields), [webhooks](/api-reference/webhooks/list-webhooks), [link token](/sdk/create-link-token) | Not used |

`category` is `hris`, `ats` or `lms`. Sending a connector token where it is not used is harmless; omitting it where it is required returns an error rather than an empty result.

## A third header on writes

Four HRIS write endpoints also take `X-Idempotency-Key` - `POST /employees`, `/employee-payroll-runs`, `/time-off` and `/timesheet-entry`.

```
X-Idempotency-Key: <UNIQUE_KEY>
```

Passthrough does not accept it. For how to choose a key, what a replay returns and how to handle a `409`, see [Idempotency](/guides/reading-writing/writing-data/idempotency).

## Auth errors

| Code | Cause |
| - | - |
| `401` | API key missing, malformed, or from the other environment. Check for the `Bearer ` prefix and a single space |
| `403` | Credentials valid but not permitted here - a token used against a different category, or a model whose writes are disabled for that integration |

A `200` with no records is not an auth problem - the connector has no synced data yet. See [Sync status](/guides/troubleshooting/sync-status).

## Related

* [Rate Limits](/api-reference/basics/rate-limits) - enforced per connector token, not per API key
* [Environments](/get-started/environments) - why a key works against one and not the other
* [Find the source of an error](/guides/troubleshooting/errors) - when the failure is on the sync rather than your request


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.