API keys

An API key lets a script, a notebook or an MCP client reach your figures without a browser session. Keys are issued one at a time from Settings → Access (/reglages/acces), each carrying its own list of permissions.

The tab has two opposite halves, and they are not the same kind of secret. What reaches Badlen is the keys you hand out. What Badlen reaches is the provider key Badlen presents to an outside service when it goes looking for a price. No API key can read that second half.

Issue a key

1. Open Settings → Access and press New key.

2. Name it after whatever will hold it. The name is all you will have later to decide which key to revoke, so “Analysis notebook” beats “key 2”.

3. Tick its permissions. They come in two groups: seven that read and two that write.

4. Set an expiry date, or leave it empty for a key that never expires. A date already past is refused.

5. Press Create the key.

The key is shown once

The key appears in full on the card that follows, and nowhere ever again: Badlen stores only its SHA-256 hash, so it cannot show it to you a second time. Copy it before you dismiss the card. Lose it and the only way forward is to revoke the key and issue another.

The nine permissions

Each one opens a fixed set of routes and nothing else. The full request and response of every route is in the REST API reference, which lists the thirteen routes a key reaches and the scope each of them requires.

Permission	What it opens
accounts:read	The accounts, with their value, gain and asset class
dashboard:read	Net worth and its allocation
insights:read	The achievement cards and their statistics
transactions:read	The recent operations
prices:read	The last known price of each asset
positions:read	Holdings by security, with latent and realised gains
analytics:read	Value series, drift, drawdown, milestones, and the metrics built on them
transactions:write	Importing a batch of operations into an account, and its dry run
accounts:write	Creating an account, setting a balance, adding a holding

Nothing on that list deletes, which is a decision of the project rather than an omission: what a leaked key can do to your data is additive, and additive damage stays visible. It is not the same as nothing being overwritten: a balance replaces the one already set for that day, and adding a holding sets the fund’s expense ratio, which every line of that fund then reads.

Living with a key

A key reaching a route its permissions do not cover is answered 403, so a key issued one tick short works everywhere but in the one place it is missing. The key list shows each key’s first eleven characters, its permissions, the date it was last used and the date it expires. That is enough to tell a key still in service from one nobody calls any more.

Revoke takes effect at once and cannot be undone. A revoked key answers 401 on every route from that moment.

The demonstration account cannot issue or revoke keys: the whole card sits behind its veil, because minting one there would hand the next visitor a live credential.