Authentication

Every request to the API is authenticated with a Billey personal access token, sent as an HTTP bearer token.

The Authorization header

Send the token in the Authorization header, prefixed with Bearer :

Authorization: Bearer 7|billey_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The token has two parts joined by a pipe — the token id, then the secret (for example 7|billey_…). Send the whole string exactly as Billey gave it to you.

curl https://billey.nl/api/v1/invoices \
  -H "Authorization: Bearer 7|billey_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A missing or invalid token is rejected with 401 Unauthorized:

{ "message": "Unauthenticated." }

There is no cookie, session, or OAuth flow — the bearer token is the only credential the API accepts. Always send it over HTTPS, and treat it like a password.

One token, one book

A token is bound to exactly one administration (book). There is no account-wide key and no book id in any URL: the token decides which book every request reads and writes. A firm managing several client books holds one token per book. See Tokens for how tokens are issued and scoped.

Abilities are checked twice

A token carries a fixed set of abilities (for example invoices:read, clients:write) chosen when it is created. Every request is authorised in two independent layers:

1. The token's frozen abilities. The ability list is a snapshot taken at issue time. If the token was not granted invoices:write, no POST /api/v1/invoices will ever succeed with it.
2. The account's live permission. On every request Billey additionally re-checks that the account behind the token still holds the matching permission in the app right now. If a teammate's access to the book is downgraded or revoked, their tokens stop working immediately — even though the token's own ability list is unchanged.

A request that clears neither layer gets 403 Forbidden, and an ability failure names what was missing:

{
  "message": "This token does not have the 'invoices:write' ability.",
  "required_ability": "invoices:write"
}

The full list of abilities, and which resources each one unlocks, is on the Tokens page.