API keys

Issue org-scoped API keys for the Brand Stack CLI and your own scripts. Per-key read/write scope, one-time display, revocation, and a visible last-used timestamp.

You do not need an API key to use Brand Stack from an AI client. The MCP connector authenticates with OAuth during setup, and every tool works over that connection, including moving a local screenshot into the workspace (agents do it keylessly through create_upload_link).

API keys are the second, optional path: they let the brandstack CLI and your own scripts call the same workspace tools from a terminal or CI, without an interactive OAuth flow. They are managed in Settings → Developer → API keys by workspace admins.

What a key can do

A key is scoped per key at creation:

Scope	Allows
Read	Listing and fetching brands, products, personas, projects, documents, assets, and the credit balance
Read + write	Everything above, plus image intake (`capture_screenshot`, uploads, `create_upload_link`, all free) and generation (`create_mockup`, `create_scene`, which consume workspace credits)

Credits, rate limits, and entitlements are enforced server-side on POST /api/mcp, the same endpoint MCP connectors use, so a call behaves identically (same rules, same error messages) whether it came from the web app, the CLI, or an MCP client.

The rate limit is 120 requests per minute per key, well above a working agent session and low enough to stop a runaway loop. Going over returns HTTP 429 with a Retry-After header; wait that many seconds and retry.

Issuing a key

Open Settings → Developer as a workspace admin
Under API keys, name the key (e.g. “CI”, “Claude Code”), choose whether to allow write, and click Create key
Copy the key (bsk_…) immediately; it is shown exactly once. Only a SHA-256 hash is stored, so it cannot be recovered later

The list shows each key’s display prefix, scope, creation time, and last used timestamp, so unused or unexpected keys are easy to spot.

Using a key

With the CLI (stored in your OS config directory, never in a repository or working directory):

brandstack login          # paste the key when prompted; verified before storing
brandstack list-brands
brandstack create-mockup --persona-id <id> --out mockup.png

Or via the environment, for CI and scripts:

BRANDSTACK_API_KEY=bsk_… brandstack get-credits

Or directly against the API (JSON-RPC, MCP tools/call):

curl -X POST https://www.brandstack.dev/api/mcp \
  -H "Authorization: Bearer bsk_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_brands","arguments":{}}}'

Revoking a key

Click Revoke next to the key. The next request using it receives a 401; the CLI explains that the key was rejected and how to re-authenticate. Revocation is immediate and permanent; issue a new key to restore access.

Keys are also revoked automatically when the admin who created them leaves the workspace, along with any MCP connections they authorized. A key is workspace access, so it ends when the membership behind it does.

Free tools never need a key

The free tools (utm-builder, color-palette-from-image, launch-image-resizer, …) run entirely locally: no key, no config read, no network. Only workspace commands touch credentials.