API keys and the developer API
An API key lets something outside The Saucery, such as Home Assistant, a kitchen dashboard or a script you wrote, reach your family's shopping list, meal plan and recipes. The full reference, with every endpoint and field, is at /developers.
Who can make a key
- Only a family admin can make or revoke keys.
- Making a key needs Saucery Pass. Without it, the API Keys screen says so and offers Saucery Pass.
- A key belongs to the family, not to the person who made it.
Making a key
On iPhone: Settings > API Keys, then + (or Create API Key if you have none yet). The row is only in Settings for admins.
On Android: Settings > API keys, then Create API key.
Give the key a name you'll recognise later, such as "Kitchen tablet", and tap Create. The key is shown once, straight after you make it. Copy it somewhere safe then: The Saucery keeps only a fingerprint of it and can't show it to you again. If you lose it, revoke it and make a new one.
Keys are made in the apps. The web app doesn't have an API Keys page.
What an integration can do
With a key, an integration can:
- Read the shopping list, one line or all of them.
- Add to the shopping list, one line at a time or up to fifty in one request.
- Change a line: rename it or set how many packs to buy. A line someone typed in can have its amount and aisle changed too; a line from the meal plan takes its amount from the recipes.
- Tick or untick a line. The request says which, so sending it twice leaves the line the way you asked. A retry over a patchy connection won't undo it.
- Remove a line.
- Read the meal plan.
- Read the recipe book: list and search the family's recipes, and fetch one with its ingredients and method. A recipe someone in the family keeps private stays out of it.
An integration can't change the meal plan or a recipe, and it can't see anything outside your family.
Keys made before 21 October 2026
Reading recipes arrived on 21 October 2026, and a key made before then wasn't given permission for it. If your integration gets a refusal when it asks for recipes, make a new key and swap it in, then revoke the old one.
Revoking a key
On iPhone, swipe left on the key and tap Revoke. On Android, tap the bin beside it. Either way you're asked to confirm, and anything using the key stops working straight away.
Each key in the list shows when it was last used, or Never used, which helps you find the one to revoke. Revoke a key if it might have leaked: anyone holding it can read your list, plan and recipes and change the list.
If your Saucery Pass ends
The family keeps its keys. While the family doesn't have Saucery Pass, every request with them is refused, and they start working again the moment the family subscribes. An admin can still see the keys and revoke them in the meantime.
Limits
A key can make 120 requests a minute. Past that, the API asks the integration to slow down and try again shortly.