API Keys

Purpose

Each page under /docs/keys/ describes one secret your project needs: what it's for, the exact permissions or scopes it must have, how to create one in the provider's dashboard, and the env var name to write it to.

These pages are fetched live by the deploy agent during npx mastrakit deploy. The agent never sees the raw key — it walks you through creating one, asks you to save it to .env.dev-secrets, and then runs mastrakit doctor --key X to validate it against the provider's API. See ADR-0015 for the full design.

If a page goes out of date (provider renamed a dashboard section, changed required scopes), edit the markdown — no CLI release needed.

Page template

Every page follows this shape so the deploy agent can parse it consistently:

---
title: <Provider> <Key Name>
description: <one-line summary>
---

## Quick reference

- Env var: `KEY_NAME`
- Required for: <scaffold component(s)>
- Permissions / scopes: <exact list>
- Validation: `mastrakit doctor --key KEY_NAME`

## Create one

1. Step-by-step with current dashboard paths
2. ...

## Add to your project

Paste into `.env.dev-secrets` (gitignored):

\`\`\`
KEY_NAME=<paste>
\`\`\`

## Common validation failures

- `❌ missing permission X` → ...
- `❌ key revoked` → ...

Why secrets stay out of the agent's context

Raw CLOUDFLARE_API_TOKEN, STRIPE_SECRET_KEY, etc. would persist in:

• Agent CLI transcripts on disk (e.g. ~/.claude/)
• Cloud sync (Cursor sync, Codex telemetry)
• Provider abuse-review queues

So the deploy agent reads your .env.dev-secrets only via mastrakit doctor, which prints ✅ / ❌ <specific-permission> and never echoes the value.