Using the API
Permission keys
The 48 permission keys that guard every action, what each one allows, the default keys of each role, and how scopes and modes work for API keys and MCP tokens.
Every action in Free Invoice Automation is guarded by exactly one permission key, written module.action, such as documents.create or payments.refund. No action exists without one. The same key is checked whether the action comes from the web app, the REST API, an MCP client, the CLI, a store connector or the AI agent, so no tool is a back door.
This page lists all 48 keys, the default keys of each role, and how keys become scopes on API keys and MCP tokens.
How permissions are checked
For every request, the API:
- works out the actor (a member's session, an API key, an MCP token) and the account,
- loads the actor's role at that moment (permissions are read per request, never cached in the session),
- checks the action's permission key against the role, and for keys and tokens also against their scopes,
- checks the business scope: every role except Owner can be limited to some businesses.
If the role lacks the key you get permission_denied (403). If the API key or token lacks the scope you get scope_missing (403). If the business is outside your scope you get business_out_of_scope (403). Each endpoint page names the key it needs.
The full catalogue
Businesses
| Key | Allows |
|---|---|
businesses.view | See businesses, their tax rates and numbering sequences, and the pay-me page settings |
businesses.manage | Create, update and delete businesses; upload a business logo |
Documents
| Key | Allows |
|---|---|
documents.view | List and read documents, versions and activity, overdue lists, PDFs, send previews, messages, PDF templates, reminder sequences, late-fee policies, recurring schedules, payment schedules and saved views |
documents.create | Create invoices, estimates and receipts; convert estimates; manage recurring schedules; invoice unbilled time and expenses |
documents.edit | Update documents (a sent one gets a revision), delete drafts, apply client credit, set a promise to pay, manage payment schedules |
documents.send | Send documents and reminders; create and revoke share links |
documents.void | Void a document |
documents.credit | Create a credit note |
Clients
| Key | Allows |
|---|---|
clients.view | List and read clients, their contacts and client credit |
clients.create | Create clients |
clients.edit | Update clients; add, change and delete client contacts |
clients.delete | Delete clients (soft delete) |
Items
| Key | Allows |
|---|---|
items.view | List, read and export saved items |
items.manage | Create, update, archive and import saved items |
Payments
| Key | Allows |
|---|---|
payments.view | See payments, payment status, payment proofs and a client's saved payment methods |
payments.record | Record and delete manual payments; accept or reject payment proofs |
payments.refund | Refund a payment |
payments.auto_charge | Turn auto-charge on or off for a recurring schedule or instalment (from March 2027) |
Rails, senders and templates
| Key | Allows |
|---|---|
rails.manage | List rails; connect, update, verify and delete payment connections (Stripe, bank transfer, Whop, local QR rails); choose a business's payment methods; edit the pay-me page |
senders.manage | Connect and manage email senders, such as your own SMTP |
templates.manage | Create and edit message templates and PDF templates |
Reminders and late fees (from January 2027)
| Key | Allows |
|---|---|
reminders.manage | Create, edit and delete reminder sequences |
late_fees.manage | Create, edit and delete late-fee policies |
late_fees.waive | Waive a late fee that was applied (audited) |
Contracts (from March 2027)
| Key | Allows |
|---|---|
contracts.view | List and read contracts; download signed contracts |
contracts.manage | Create contracts and new versions |
contracts.sign | Countersign a contract for the business |
Time and expenses (from April 2027)
| Key | Allows |
|---|---|
time.view | See time entries and unbilled time |
time.log | Log time, start and stop timers, change or delete your own entries |
time.manage | Change or delete other members' time entries |
expenses.view | See expenses |
expenses.manage | Record, change and delete expenses; upload receipts |
Reports
| Key | Allows |
|---|---|
reports.view | Run reports, including aged receivables (from January 2027) |
reports.export | Export reports as CSV or PDF |
Accounting sync and ledger
| Key | Allows |
|---|---|
accounting.manage | Connect QuickBooks Online or Xero, edit the mapping, backfill, see sync status, retry and disconnect (from May 2027) |
ledger.view | See ledger accounts, journal entries, periods, bank transactions and ledger reports (from June 2027) |
ledger.journal | Post and reverse journal entries |
ledger.manage | Manage the chart of accounts, apply a template, lock and unlock periods, import bank statements and match transactions |
AI
| Key | Allows |
|---|---|
ai.use | Run the AI invoice agent and read its runs; read receipts with AI |
ai.manage | Manage agent automations and your own AI provider keys |
Settings, team and integrations
| Key | Allows |
|---|---|
settings.view | Read settings, the account, members and usage |
settings.manage | Change settings, the account, tax rates and numbering patterns |
team.manage | Invite, update, deactivate, reactivate and remove members; create, edit, reset and delete roles |
integrations.manage | Create and revoke API keys; manage outgoing webhook endpoints, test them and redeliver; link and manage store connector installs |
audit.view | View the audit log (Team) |
billing.manage | Manage the Team subscription, the billing card and credit packs |
Account (Owner only)
| Key | Allows |
|---|---|
account.export | Export all account data |
account.delete | Delete the account |
account.delete and ownership transfer can never be given to a role other than Owner. Ownership transfer is not a key you can tick: it is checked against the Owner role itself. That is why the catalogue has 48 keys and no transfer key.
Default roles
Every account has five roles: Owner, Admin, Editor, Viewer and Accountant. The matrix shows the keys each one gets by default. Y means the role has the key.
| Key | Owner | Admin | Editor | Viewer | Accountant |
|---|---|---|---|---|---|
| businesses.view | Y | Y | Y | Y | Y |
| businesses.manage | Y | Y | |||
| documents.view | Y | Y | Y | Y | Y |
| documents.create | Y | Y | Y | ||
| documents.edit | Y | Y | Y | ||
| documents.send | Y | Y | Y | ||
| documents.void | Y | Y | |||
| documents.credit | Y | Y | |||
| clients.view | Y | Y | Y | Y | Y |
| clients.create | Y | Y | Y | ||
| clients.edit | Y | Y | Y | ||
| clients.delete | Y | Y | |||
| items.view | Y | Y | Y | Y | Y |
| items.manage | Y | Y | Y | ||
| payments.view | Y | Y | Y | Y | Y |
| payments.record | Y | Y | Y | ||
| payments.refund | Y | Y | |||
| payments.auto_charge | Y | Y | |||
| rails.manage | Y | Y | |||
| senders.manage | Y | Y | |||
| templates.manage | Y | Y | Y | ||
| reminders.manage | Y | Y | Y | ||
| late_fees.manage | Y | Y | |||
| late_fees.waive | Y | Y | Y | ||
| contracts.view | Y | Y | Y | Y | Y |
| contracts.manage | Y | Y | Y | ||
| contracts.sign | Y | Y | |||
| time.view | Y | Y | Y | Y | Y |
| time.log | Y | Y | Y | ||
| time.manage | Y | Y | |||
| expenses.view | Y | Y | Y | Y | Y |
| expenses.manage | Y | Y | Y | ||
| reports.view | Y | Y | Y | Y | Y |
| reports.export | Y | Y | Y | Y | |
| accounting.manage | Y | Y | |||
| ledger.view | Y | Y | Y | ||
| ledger.journal | Y | Y | |||
| ledger.manage | Y | Y | |||
| ai.use | Y | Y | Y | ||
| ai.manage | Y | Y | |||
| settings.view | Y | Y | Y | Y | Y |
| settings.manage | Y | Y | |||
| team.manage | Y | Y | |||
| integrations.manage | Y | Y | |||
| audit.view | Y | Y | |||
| billing.manage | Y | ||||
| account.export | Y | ||||
| account.delete | Y |
In short: Owner has everything. Admin has everything except billing and the two Owner-only account keys. Editor does the daily work: documents, clients, items, payments, templates, reminders, time and expenses, but cannot void, credit, refund or change settings. Viewer can only read. Accountant reads everything finance-related and can also export reports and see the ledger.
Business scope
On top of the role, every member except the Owner has a business scope: all businesses, or a list. A member scoped to one business cannot see or change the others, whatever their role.
Editing roles
The matrix above is the default. What applies at run time is the account's own roles.
- On Team, every role except Owner can be edited by ticking or unticking keys, or deleted. Presets have Reset to default, which restores the keys in the matrix above. You can create custom roles from scratch or by duplicating a role.
- Owner is fixed. It always has every key, cannot be edited, reset or deleted (
role_locked), and an account always keeps at least one Owner (last_owner). - No escalation. Only a member with
team.managecan change roles, and nobody can grant a key they do not hold (permission_not_grantable). - Roles in use cannot be deleted until their members are moved (
role_in_use). - Changes apply on the next request, and every change is written to the audit log with the old and new key lists.
- On Free, the account has the Owner and one view-only Accountant, both fixed. Role editing and custom roles return
feature_locked.
See Roles and permissions and Custom roles for the app side, and the Team endpoints for the API.
Scopes on API keys and MCP tokens
API keys and MCP tokens carry scopes, chosen from the same 48 keys, plus a mode.
Scopes
- When you create a key in Settings > API keys, or approve an MCP client on its consent screen, you choose the scopes. You can only choose keys you hold yourself.
- At call time, a key is limited to the intersection of its scopes and its creator's current permissions. If the creator's role loses a key, or the creator is deactivated or leaves, the API key and MCP token lose it on the very next request.
- A key cannot gain scopes after it is created. To widen access, create a new key.
- Give each key the fewest scopes it needs. A script that only reads overdue invoices needs
documents.view, nothing else.
Modes
| Mode | Behaviour |
|---|---|
draft_only (default) | Creates drafts. Sends need "confirm": true from the caller, which should come from a person. |
auto_send | Sends run without confirm. Creating an auto_send key needs a fresh sign-in. |
In both modes, destructive actions (void, credit note, refund, auto-charge settings and the others marked D) always need "confirm": true. See Drafts and confirmations.
Typical scope sets
| Integration | Scopes |
|---|---|
| Read-only dashboard | documents.view, payments.view, clients.view |
| Billing server that creates and sends invoices | clients.view, clients.create, clients.edit, items.view, documents.view, documents.create, documents.send |
| Payment reconciliation script | documents.view, payments.view, payments.record |
| Webhook administration | integrations.manage |