---
title: API keys
description: 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](/mcp/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

1. Open **Settings → Developer** as a workspace admin
2. Under **API keys**, name the key (e.g. "CI", "Claude Code"), choose whether to allow write, and click **Create key**
3. 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):

```sh
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:

```sh
BRANDSTACK_API_KEY=bsk_… brandstack get-credits
```

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

```sh
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.