Tokens and scopes

Create scoped credentials for scripts and understand the sensitive actions they can never perform.

A personal access token gives a script or program controlled access to your budget. Depending on the scope you choose, it can read the items, forecast, and exports or also change budget data without using your password.

Making one

Account → API access → New token. A name, at least one scope, and an expiry — 30 days, 90, a year, or never.

The token is shown once, at creation. Only a hash of it is stored, so it cannot be shown again; if you lose it, revoke it and make another. It begins with ebbe_pat_, making it easier for secret scanners to recognise an accidentally committed token.

Send it as an ordinary bearer token:

Authorization: Bearer ebbe_pat_...

Up to 50 per account, expired ones included. Revoke takes effect at once.

The “last used” figure is coarse — written at most once an hour — so it is useful for “is this token still in use at all” and not for tracing individual calls.

The two scopes

Two scopes are available:

• budget:read — read the budget, the categories, the items, the balance readings, the tag settings, the forecast, and both exports.
• budget:write — create, change and delete those things. It implies read: a token with write can read, and you do not need both.

Choose read access for reporting and write access only when the program needs to maintain the budget.

What a token cannot do

Anything about your identity — changing your password or address, deleting the account, issuing another token. A credential that could mint its own replacement or destroy the account it belongs to is not a limited credential at all.

Bulk changes — importing, emptying the budget, loading demo data, or pruning. These remain in the interface, where you can review and confirm them.

Administration. No token scope can manage accounts or change the service configuration.

Rate limits

Limits are counted separately for each token. For backups, fetch an export on a schedule rather than in a loop.

The full reference

Open /api/docs for the current endpoint list. Ebbe generates this reference from the routes available to tokens, so it stays in step with the server. Its Authorize button lets you paste in a token and try a call directly on the page.

/api/openapi.json is the same thing as a machine-readable document.

When something is refused

A refusal names a code rather than a sentence, so a program can branch on it and a person can look it up. 401 means the token is unknown, expired or revoked; 403 means it is valid but lacks the scope; 409 means a ceiling was reached, and the response names which one. See limits.