Tokens

A token is how an integration authenticates, which book it can touch, and what it may do there. This page covers issuing tokens and the ability catalogue.

Creating a token

Tokens are created inside the app, per book:

1. Open the book's Settings → API tokens.
2. Your account must have two-factor authentication enabled — token creation is blocked otherwise, because a token is a long-lived credential.
3. Choose the token's abilities (see the catalogue below).
4. billey shows the plaintext token once. Copy it immediately and store it somewhere safe — it is never shown again. If you lose it, delete the token and create a new one.

Every token is bound to the book you created it under and carries an expiry. To stop a token, delete it from the same settings screen; the next request it makes gets 401.

The ability catalogue

An ability is a resource:action string. A token must be granted an ability to use the matching endpoints — and, as covered in Authentication, the account behind it must still hold the live permission at request time.

Abilities that ride along

A few read-only resources do not have an ability of their own — they ride on a related one:

• Documents are covered by expenses:read.
• Ledger entries are covered by reports:read.

Changed: time entries used to ride projects:read. They now have their own time-entries:read and time-entries:write abilities, so a token issued with only projects:read no longer reads them — reissue it with the abilities it needs. projects:read still reads projects exactly as before.

Changed: quotes used to ride invoices:read. They now have their own quotes:read (and quotes:write) abilities, so a token issued with only invoices:read no longer reads quotes — reissue it with quotes:read. invoices:read/invoices:write still read/write invoices exactly as before, and a quotes:write token deliberately cannot send, mark paid, credit-note, or delete invoices — the split exists precisely so it doesn't have to.

The read/write split is real

The split is enforced on the token, not just in the UI. A token granted only invoices:read structurally cannot write an invoice, regardless of what the user behind it is allowed to do in the web app. Issue read-only tokens to integrations that only need to sync data out — it is the tightest, safest default.

Not available as abilities

There is deliberately no ability for user management in v1. POS clients use the narrow pos-payments:read / pos-payments:write abilities: every request is still bound to one book and re-checks the live run pos permission. Native apps must acquire their credential through the authenticated sign-in flow, not by asking a cashier to paste a settings token; neither the app nor these endpoints may persist or re-display Terminal credentials.