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 halves that point in opposite directions, and they hold different kinds of secret. What reaches Badlen is the keys you hand out. What Badlen reaches is the provider key Badlen presents to an outside service: a Moralis key, which finds the ERC-20 tokens of a watched Ethereum address, as Where the data comes from explains. 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.

A permission also limits what the answers contain. A figure covered by another permission is returned only with that permission: a key ticked for the achievement cards alone gets the cards whose figures that permission covers, without the net worth or the labels of your biggest expenses, and the account an operation or a holding sits in is named only with accounts:read.

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, on purpose: a leaked key can only add to your data, and additions stay visible. Some things can still be 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 calling a route its permissions do not cover gets a 403, so a key issued one tick short works everywhere except where that tick 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.

In the online demo the card is locked: a key issued there would open an API that lives in your browser tab and nowhere else.