Invoice AI API Authentication: API Keys and Scopes

Create Invoice AI API keys in Settings, pass them as Bearer tokens on each request, and assign scopes to restrict what each key can do.

Authentication

The Invoice AI API uses API keys for authentication. Every request to a protected endpoint must include a valid key in the Authorization header. There are no sessions, cookies, or OAuth flows — just a long-lived secret you send with each request.

Creating an API Key

1. Sign in to the Invoice AI dashboard.
2. Navigate to Settings → API Keys.
3. Click Create key, give it a descriptive name, and select the scopes it needs.
4. Copy the key immediately — it is shown only once.

Guest accounts cannot hold API keys. If you signed in without an email address, add an email and password under Settings → Account before creating keys.

Treat API keys like passwords. Never commit them to source control, expose them in client-side JavaScript, or log them in plaintext. Rotate any key you suspect has been compromised from the same settings page.

Sending the API Key

Pass the key as a Bearer token in the Authorization request header:

Authorization: Bearer inv_live_...

Example

curl https://invoice.horizonpay.co/api/v1/invoices \
  -H "Authorization: Bearer inv_live_..."

All API keys begin with the prefix inv_live_ followed by a random string. Keys are tied to a single workspace; they cannot access resources belonging to a different workspace.

Scopes

When you create a key, you choose which scopes to grant. A key can only perform operations covered by its assigned scopes — requests that require a scope the key lacks return 403 Forbidden.

Granting the narrowest set of scopes your integration actually uses is good practice: if a key is leaked, the blast radius is limited.

Scope	What it allows
business:read	Read your business profile, tax ID, and bank details
clients:read	List and retrieve clients
clients:write	Create, update, and archive clients
products:read	List and retrieve products and prices
products:write	Create, update, and archive products and prices
invoices:read	List and retrieve invoices, including PDFs
invoices:write	Create, edit, and delete invoice drafts
invoices:finalize	Finalize invoices (assign an invoice number) and void them
invoices:send	Email invoices to clients
payments:write	Mark invoices as paid
webhooks:manage	Create, update, and delete webhook endpoints

A key used only for syncing invoice data to your data warehouse needs only invoices:read and clients:read. A key used by a billing automation service that creates and finalizes invoices needs invoices:write, invoices:finalize, and clients:read (to look up customers), but not webhooks:manage.

Scope inheritance

There is no inheritance between read and write scopes. A key with invoices:write cannot list invoices unless it also has invoices:read. Grant both when your integration does both.

Authentication Errors

401 Unauthorized · error

Returned when the Authorization header is missing, malformed, or contains a key that does not exist or has been deleted. See the Errors reference for the full response format.

403 Forbidden · error

Returned when the key is valid but lacks the scope required by the endpoint you called. Check the endpoint documentation for the required scope, then either add that scope to an existing key or create a new key with the correct scopes.

Example 401 response

{
  "type": "https://invoice.horizonpay.co/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API key was provided."
}

Example 403 response

{
  "type": "https://invoice.horizonpay.co/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the invoices:write scope."
}

Key Management

Action	Where
Create a key	Settings → API Keys → Create key
Rename a key	Settings → API Keys → ··· → Rename
View last-used timestamp	Settings → API Keys list
Delete (revoke) a key	Settings → API Keys → ··· → Delete

Deleting a key is permanent and takes effect immediately. Any in-flight request carrying that key will receive a 401 response. There is no grace period.

Use distinct keys per integration environment. A key for local development, a key for staging, and a key for production means you can rotate or revoke any one of them without disrupting the others.