Authentication

Markdown

Authenticate API calls with a tenant API key.

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:

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. Import jobs and ingest need ingest:write; creating or retrying an import job of invoices, counterparties, or payment methods also needs that entity's :write scope. The Events API needs events:read.

  • counterparties:read / counterparties:write
  • payment_methods:read / payment_methods:write
  • transactions:read / transactions:write
  • invoices:read / invoices:write
  • matches:read / matches:write
  • ingest:write — import jobs (/api/v1/import-jobs) and the deprecated POST /api/v1/ingest/transactions
  • events:read — the Events API (GET /api/v1/events)

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) - more than 100 requests in a minute from the key. Wait for Retry-After seconds. Import jobs and ingest have tighter limits; see Retries and rate limits.
  • Internal server error (500) - unexpected failure. The JSON body includes correlationId; retry with backoff.

Example

List counterparties with the key:

curl --request GET \
  --url https://api.invunion.com/api/v1/counterparties \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY'
Previous: Introduction Next: Pagination and sync