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

# Authentication

> How to authenticate requests to the doola Partner API.

Every request is authenticated with an API key sent in the `Authorization` header.

```bash theme={null}
Authorization: dk_live_your_api_key_here
Content-Type: application/json
```

## API keys

API keys are issued by the doola team, one per environment.

| Prefix     | Environment                            |
| ---------- | -------------------------------------- |
| `dk_test_` | Sandbox (`https://api.test.doola.com`) |
| `dk_live_` | Production (`https://api.doola.com`)   |

<Warning>
  Treat API keys as secrets. Use them only from your backend, never in client side code. A sandbox key does not work against production, and the reverse is also true.
</Warning>

Manage your keys, webhook endpoint, and event subscriptions in the doola Partner Portal, including rotating a key. Don't have access yet? [Get API access](https://www.doola.com/partner-with-us/).

## Request headers

| Header            | Required  | Description                                               |
| ----------------- | --------- | --------------------------------------------------------- |
| `Authorization`   | Yes       | Your API key, sent as the raw value (no `Bearer` prefix). |
| `Content-Type`    | On writes | `application/json` for `POST` requests.                   |
| `Idempotency-Key` | On writes | Required on create endpoints. Makes retries safe.         |
| `x-request-id`    | No        | Optional correlation id. Echoed back on the response.     |

## Idempotency

The create endpoints (`POST /v1/partner/customers` and `POST /v1/partner/companies`) require an `Idempotency-Key`.

* Use a unique value per logical operation, for example a UUID tied to your own record.
* Retrying with the same key and the same body returns the original result and never creates a duplicate.
* If a create fails before it commits — a validation or pre-check `4xx`, or a transient `5xx` — the key is released. Fix the request and retry with the **same** key (you do not need a new one).
* Once a create has succeeded, reusing its key with a different body returns `409 E_IDEMPOTENCY_KEY_REUSED`.
* While a create with a given key is still in flight, a concurrent retry of that key returns `409 E_IDEMPOTENCY_IN_PROGRESS`; retry after a short delay.