Skip to main content

​
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:

​
Example

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.
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

​
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.
​
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

​
Example 403 response

​
Key Management

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.