# Authentication

Authenticate Document API calls with a tenant API key.

- HTML docs: https://www.invunion.com/knowledge-base/api/authentication/
- Markdown docs: https://www.invunion.com/knowledge-base/api/authentication.md

Create a tenant API key in Settings. The secret is shown once. It always starts with `uk_live_`. Store it like a password; Invunion cannot show it again. Keys may have an optional expiry.

Send the key on every request:

```bash
Authorization: Bearer uk_live_YOUR_API_KEY
```

The tenant is taken from the key. Do not send a tenant id in the URL or body.

## Scopes

Each key has scopes. GET, HEAD, and OPTIONS need the matching `:read` scope. Create, update, delete, bulk import, reconcile, cancel, and match writes need `:write`. `write` does not imply `read`. Pushing transactions through ingest, and reading ingest jobs, need `ingest:write`.

- `counterparties:read` / `counterparties:write`
- `payment_methods:read` / `payment_methods:write`
- `transactions:read` / `transactions:write`
- `invoices:read` / `invoices:write`
- `matches:read` / `matches:write`
- `ingest:write` — POST `/api/v1/ingest/transactions` and GET ingest jobs

To rotate a key, create a new one, switch the integration, then revoke the old key. A tenant may have up to 10 active keys, so both can overlap during the switch.

## Errors

- `Missing Bearer token` (401) - the Authorization header is missing or is not a Bearer token.
- `Invalid or revoked API key` (401) - the key is unknown, malformed, expired, or has been revoked.
- `API key is missing scope …` (403) - the key does not include the scope this operation needs. Write does not imply read.
- `Too many requests, please try again later` (429) - wait for `Retry-After` seconds. Ingest has a tighter per-key limit.
- `Internal server error` (500) - unexpected failure. The JSON body includes `correlationId`; retry with backoff.

## Example

List counterparties with the key:

```bash
curl --request GET \
  --url https://api.invunion.com/api/v1/counterparties \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY'
```