> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magicmealkits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API key authentication and license tiers for the Magic Meal Kits API.

## API key

Every API request authenticates with the API key set on your deployment
(`MMK_API_KEY`). Send it in the `X-API-KEY` header:

```bash theme={null}
curl -X POST "https://magic-meal-kits-xxxxx.run.app/api/v1/youtube/transcript/v2" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "format": "json"}'
```

The MCP endpoint also accepts `Authorization: Bearer your-api-key` for clients that
prefer the bearer scheme (e.g. Claude.ai). See [MCP Overview](/mcp/overview).

## Where to get your API URL and key

Your deployment's **API URL** (your Cloud Run host) and **API key** are shown on the
**app status / connection page in the Magic Meal Kits app** — not configured by hand.
Open your deployment there, copy the URL and key, and use them wherever you call the API.

In the Make.com custom apps, you register these once on the connection: enter the
**Magic Meal Kits service URL** and **API key**, and every module reuses them. Connection
setup and management is centralized at
[make.magicmealkits.com/connections](https://make.magicmealkits.com/connections).

<Note>
  For most products (Plaud, Tiro, Threads) the per-service credentials are stored
  **server-side** on your deployment — the MMK API key is the only secret the caller
  handles. Connect or reconnect those accounts (including the Threads OAuth account) from
  the Magic Meal Kits app, not through these endpoints. If a stored token expires,
  reconnect from the app and redeploy your server with the latest version.

  **Notion is the exception:** the caller supplies the Notion token per request via the
  `X-Notion-Token` header (plus `X-Notion-Space-ID` / `X-Notion-User-ID` for unofficial
  operations). See the [Notion overview](/api-reference/notion/overview).
</Note>

## License tiers

Endpoints are gated by your license tier:

| Tier      | Applies to                                                           |
| --------- | -------------------------------------------------------------------- |
| **Basic** | Core utility endpoints (group-level default on most routes)          |
| **Pro**   | Pro-only features — added per-route; the default for newer endpoints |

A Pro-gated route called with a Basic key returns a license error. Most Pro gates
(`license.RequirePro()` — **Plaud**, **Tiro**, and **Notion**'s Pro-only operations)
reject with **`400`** and the message `you are not a magic meal kits PRO user`. The
**YouTube** `metadata` Pro gate is the exception — it returns **`403`** with
`Pro account required`. Per group: YouTube transcript is Basic (metadata is Pro); Plaud
and Tiro are Pro-only; Notion is Basic with selected Pro-only operations.

## Error format

Error shapes vary slightly by group — rely on each operation's response schema. Most
errors carry an `error` (or `success: false` + `error`) field with a message.

| Status      | Meaning                                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400`       | Invalid parameters/body, or a `license.RequirePro()` route called with a Basic key (`you are not a magic meal kits PRO user`) |
| `401`       | Missing/invalid API key, or a rejected third-party credential (reconnect the account)                                         |
| `402`       | Quota exhausted (e.g. Plaud transcription)                                                                                    |
| `403`       | YouTube `metadata` Pro gate (`Pro account required`)                                                                          |
| `404`       | Not found                                                                                                                     |
| `409`       | Resource not ready yet (e.g. transcript still generating)                                                                     |
| `429`       | Rate limited                                                                                                                  |
| `500`–`504` | Upstream/server error or timeout                                                                                              |