Authentication

Markdown

Authenticate Document 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. 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:

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: List counterparties