# API keys and scopes

> How FoodPerfect API keys work — creating, scoping, expiring and revoking them, and how to keep them safe.

Every request carries an API key as a bearer token:

```http title="Header"
Authorization: Bearer fp_live_8f2c…
```

A key acts as the FoodPerfect account that created it: same Brand DNA, library, schedule and balance. Anything done with the key counts as done by that account ([Terms, §8](https://app.foodperfect.ai/legal/terms-of-service.md)).

## Create a key

In the app, open **[Settings → API Keys](https://app.foodperfect.ai/settings)** and click **Create API Key**. Choose:

| Field | Options |
|---|---|
| **Label** | A name you'll recognise later, e.g. "Cursor, laptop". |
| **Environment** | **Live** (`fp_live_…`) or **Test** (`fp_test_…`). Both reach the same account and both spend real balance; the prefix only helps you tell keys apart. |
| **Expiry** | Optional date after which the key stops working. |
| **Scopes** | Which tools the key may call (below). |

The full key is shown **once**. FoodPerfect stores only a SHA-256 hash, so a lost key can't be recovered. Revoke it and make a new one.

## Scopes

Scopes limit which tools a key can call. A call outside them fails with `unauthorized`.

| Scope in the app | Value | Allows |
|---|---|---|
| All MCP Tools | `*` | Every tool. |
| Read Tools | `get_*` | `get_account`, `get_brand_dna`, `get_generation`, `get_job_status`, `get_connect_link`, `get_inbox_item`, `get_inbox_settings`, `get_brand_analysis_status`. |
| List Tools | `list_*` | `list_generations`, `list_assets`, `list_scheduled_posts`, `list_reel_presets`, `list_inbox`. |
| Generation Tools | `generate_*` | `generate_photo`, `generate_promo`, `generate_menu`, `generate_video_from_image`, `generate_reel_storyboard`, `generate_reel_script`, `generate_reel_music`, `generate_post_example`, `generate_publish_schedule`, `generate_scheduled_post_content`. |
| Render Reel | `render_reel` | `render_reel`. |

Tools outside these patterns (`ping`, `photo_prompt`, `edit_image`, `remove_background`, `upscale_image`, `upload_asset`, `update_brand_dna`, `animate_reel_shot`, `create_reel`, `draft_reply`, `send_reply`, `set_inbox_status`, `sync_inbox`, `update_inbox_settings`, `moderate_comment`, `run_brand_analysis`, `regenerate_brand_dna`, `publish_post_now`, `schedule_reel_post`, `delete_*`, `confirm_action`, `finalize_connection`, `resolve_reel_generators`, `scrape_trending_hooks`) need **All MCP Tools**.

**Backward compatibility**: The scope `publish_posts_now` (old spelling) is accepted as `publish_post_now`.

**Recommended setups**

- *Assistant that plans and reports:* Read Tools + List Tools.
- *Content assistant:* Read + List + Generation Tools. It can spend balance but can't publish or delete.
- *Full social media agent:* All MCP Tools. Publishing and deleting still need [approval](/docs/approvals/).

## Rotate and revoke

Revoke a key in Settings → API Keys at any time; it stops working on the next request. To rotate, create the new key, update your client, then revoke the old one. Each key shows when it was created, last used and when it expires.

## Keep keys safe

- One key per client or machine, so you can revoke one without breaking the rest.
- Store keys in environment variables, a secret manager, or your client's secure input (VS Code `inputs`, for example). Never in a repo, a screenshot or a shared doc.
- Give each key the fewest scopes it needs, and an expiry for anything temporary.
- Leaked a key? Revoke it first, then email [security@foodperfect.ai](mailto:security@foodperfect.ai).

## Rate limits

Each key may make **60 tool calls per minute** by default (`initialize` and `tools/list` don't count). Over the limit you get HTTP `429` with a `Retry-After` header. Need more? Email [support@foodperfect.ai](mailto:support@foodperfect.ai). See [Errors, rate limits & idempotency](/docs/errors/).