When you need a key
- No key: list and install starter themes, validate
theme.json, read concepts, resolve shared themes. - Any key (free or Pro account): install your own saved themes, list and read them, save and update themes (up to your plan limit), generate themes with AI (up to your plan quota), check your quota.
- Pro plan: a key from a Pro account also installs the Pro starter themes and has unlimited saves.
Create a key
Open Account settings → API keys in the builder (any signed-in account). The full key is shown once. It is stored hashed and cannot be recovered, so copy it straight into your client. Revoke it from the same screen at any time; clients using it lose access immediately. If a Pro plan lapses, the key keeps working with free-plan limits.
Send the key
Every client sends the key the same way, as a request header:
Authorization: Bearer <your key>
Where the header goes depends on the client. Use the Add your API key section of your client's guide, listed on the MCP overview.
Keep the key out of git:
- Prefer an environment variable named
SHADS_API_KEYwhere the client supports it (Cursor, Claude Code, Codex, Windsurf). - VS Code prompts for the key and stores it securely.
- Zed and Gemini CLI need the key written into the config file: keep that file out of version control.
- Do not put a key in a shared project file such as
.cursor/mcp.jsonor.mcp.json.
When the key is wrong
The connection keeps working with public tools. Run connection_status (ask your assistant: "Use the shads MCP server and run connection_status"). It reports the reason, for example an invalid or revoked key, a lapsed plan, or a missing header.
Also see troubleshooting.