API access

YAFFA has an API that its own web interface uses, and that you can use as well, for example from a script, a spreadsheet, or another automation. You access your own data, with the same per-user separation as in the web interface.

note

Personal API tokens and the generated API documentation are available since YAFFA 4.0.

Create a token

You create and manage tokens in your user settings.

1. Give the token a name that helps you to remember what it is used for.
2. Select the permissions (abilities) of the token, see below.
3. Optionally, select an expiry date. Tokens always expire: if you don't select a date, or select one that is too far, the maximum lifetime of your instance applies (365 days by default, see advanced configuration).
4. Copy the token when it is displayed. It is shown only once, and it cannot be retrieved later.

You can revoke a token at any time in the same place. Expired tokens are removed automatically by a daily scheduled task.

Permissions of a token

Ability	Grants
read	Read access to your data. Every token has it, as even creating a transaction requires reading the accounts, payees, or categories it refers to.
write	Creating, changing, and deleting your financial data: accounts, transactions, investments, categories, payees, tags, and import profiles.
settings	Reading and changing account and security settings, and the configuration of integrations, such as AI providers, Google Drive, and investment price providers.

write and settings are independent of each other. A request that needs an ability the token does not have is refused with a 403 status. Give each token only what it needs.

Requests from the web interface are not affected by these abilities.

Call the API

Send the token as a bearer token. The API is available under the /api/v1/ path of your instance. For example, to list your budgets:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json" \
     https://your-yaffa-domain.com/api/v1/budgets

A revoked or expired token is refused as unauthenticated (401).

Rate limit

Each user can send 120 requests per minute. A script that sends more receives a 429 status until the next minute, without affecting other users of the instance.

Amounts are decimal strings

Money amounts, prices, and quantities are returned as decimal strings, such as "12.3400000000", and not as JSON numbers, to avoid rounding errors. Parse them into a decimal type in your code. This affects fields such as the amounts of transaction items, the amounts and prices of transactions, investment prices, opening balances, and currency rates. The report endpoints still return numbers.

API documentation

YAFFA can generate interactive documentation of its API, available at /docs/api on your instance. It is always available when the application runs in the local environment. In all other environments, the SCRAMBLE_PROD_AUTH setting of your .env file controls who can see it.

Value	Who can open /docs/api
none (default)	Nobody, the documentation is hidden.
user	Logged-in users with a verified email address.
guest	Anyone, including visitors who are not logged in.

The documentation only describes the API of the open-source application. It does not expose your data. Note that it lets visitors send test requests from the page, which is useful for a public demo, but you might not want it on a private instance. See advanced configuration.