API tokens

An API token lets a program talk to your instance the way the app does, without a login form. Use one for a script, a second instance, or an AI assistant.

Only admins can issue tokens, under Settings → API.

Creating a tokenAdminsAdmins only

1. Open Settings → API and choose Create token on the "API tokens" card.
2. Give it a name that says where it will live, such as "MCP on the laptop". That name is how you tell tokens apart later.
3. Choose what it may do. Recipes and Accounts are set separately, each on a ladder of None, Read and Write, where every step includes the ones before it; the sentence under the ladder says what the chosen step allows. Recipes has a fourth step, Delete — a Write token can create and edit recipes but never delete one. Give a token the least it needs — but not nothing: as soon as both ladders stand at None, the dialog says "Please choose at least one kind of access" under them, and Create does nothing until one of them is raised.
4. Choose its Lifetime: 30 days, 90 days, 1 year, or no expiry.
5. Choose Create.

The token is now shown once. Copy it, then choose I have saved it to close the dialog — it cannot be recovered afterwards. If you lose it, revoke it and create a new one.

Using a token

Send it as a bearer token, in place of the session cookie:

curl -H "Authorization: Bearer rzp_..." https://your-instance/api/v1/recipes

A token also opens the image files and the OpenAPI document, so a client can discover the API on its own.

What a token cannot do

A token acts as the admin who issued it, limited by its scopes. Some things are out of reach whatever scopes it carries:

• managing API tokens, so a token can never list, issue or revoke one
• anything about its own account: reading it (GET /api/v1/auth/me), changing its password, display name, color, photo or email address, or looking up which colors are taken
• signing out, or any other session mechanics
• changing the household settings (PATCH /api/v1/settings): editing rights, public links and link previews; reading them works with Recipes: Read
• issuing or revoking a setup link for an account (/api/v1/users/{id}/setup-link)
• public links (/api/v1/shares, /api/v1/recipes/{id}/public-share): listing, creating or revoking them
• the mail settings and the test mail (/api/v1/settings/mail)
• anything at all, once the admin who issued it loses the admin role or is deleted

One consequence worth knowing before you automate account cleanup: deleting a member does not delete their recipes, it transfers them to the account that performed the deletion — which for a token means the admin who issued it.

It also inherits that admin's rank, which is what decides how far Accounts: Write reaches. Issued by an ordinary admin, a token can add and delete members but cannot make anyone an admin, because the account behind it cannot either (see People). Issued by the owner, it can.

So if you are the owner and want a token that is unable to hand out admin rights, create a second admin to act as a service account and issue the token while signed in as them: the limit then comes from the account rather than from a setting anyone could forget.

Recipe editing rights never narrow a working token either: admins may edit and delete every recipe, locked or not, and so may their tokens with Recipes: Write. That lasts only as long as the account behind the token is an admin — a token always acts with its issuer's current role, and stops working once that role is gone. Only the owner can change the household's editing setting, and only in the browser.

Revoking a tokenAdminsAdmins only

Choose Revoke on its tag. Rezepte asks first ("Revoke token?"); once you confirm, the token stops working immediately. This cannot be undone.

Expired tokens stay in the list, marked as such, until you revoke them — so you can always see why an integration stopped.

Each token hangs in the list like a key tag. The bar under its name shows how much of its lifetime has passed: the mark is today, the dot is when it was last used, and an expired token is stamped "Expired". The plaques below show what it may do for each area, as dots from none to the highest step. Next to the name you find the first characters of the token, which is how you match a tag to the entry in a program's configuration. "Last used" is accurate to the hour.

The list shows your own tokens. Switch on "Everyone in the household" to see every admin's tokens, each marked with who issued it, and pick a person to show only theirs.