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 or POS in v1 — those areas have no API surface at all. See the Introduction for the full list of what the API does not cover.