Authentication
This page has been cleared and is ready for updated Builder Studio documentation.
All programmatic access to BuilderStudio uses bearer authentication with a workspace-scoped API key. The key is sent in the standard Authorization: Bearer … header on every request, and it both identifies the workspace and carries the scopes that gate what the request may do.
Key families
Three different credential families show up across BuilderStudio. They are not interchangeable — each surface accepts only the family it was designed for.
| Prefix | Family | What it authenticates |
|---|---|---|
builder_ | Workspace API key | The MCP gateway and the direct HTTP endpoints. Created from the dashboard under Security → Workspace API Keys. Scoped to a single workspace. |
| (opaque OAuth token) | OAuth 2.1 bearer token | The MCP gateway, for clients that complete the OAuth authorization flow instead of pasting a static key. Scopes are derived from the consent grant and re-checked against the user's current workspace role on each call. |
umcp_ (when enabled) | Published-server credential | A separate credential for protected published user MCP servers — not the BuilderStudio workspace surface. See the Marketplace and Builder MCP & CLI. |
builder_… value is returned exactly once. Store it securely. BuilderStudio only keeps a SHA-256 hash plus a short display prefix, so a lost key cannot be recovered — create a new one and revoke the old.Scopes
A builder_ key carries one or more of the following scopes. Each endpoint and MCP tool requires a specific scope; a request whose key lacks the required scope is rejected with 403 and an error naming the missing scope. New keys default to read:canvases and run:workflows unless you choose otherwise.
| Scope | Grants |
|---|---|
read:canvases | List canvases, read canvas state, nodes, edges, and run history. |
read:assets | List and read canvas and workspace assets. |
run:workflows | Trigger executions, poll run status, and read execution outputs. |
write:canvas | Create canvases and mutate nodes, edges, and canvas structure; register webhook triggers. |
write:assets | Upload, place, rename, move, and tag assets. |
delete:canvas | Delete or archive canvases. |
delete:assets | Trash or purge assets. |
manage:integrations | Create, edit, list, and revoke workspace integration connections. |
read:billing | Read credit balance, transactions, billing summary, and the FOCUS export. |
Creating a key
Open Workspace API Keys
In the dashboard go to Security → Workspace API Keys for the workspace you want the key to act on.
Choose a name, scopes, and expiry
Pick the minimum scopes the integration needs. Expiry is optional; when set it must be between 1 and 365 days.
Copy the key once
The full
builder_…value is shown a single time. Paste it into your client config or secret store before leaving the page.
You can also manage keys programmatically through the MCP API-key tools (list / create / revoke) — see Endpoints.
Sending the key
# MCP gateway (BuilderStudio app origin)curl -X POST https://<your-app-host>/api/mcp \ -H "Authorization: Bearer builder_..." \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' # Direct HTTP endpoint (Convex HTTP actions host)curl https://<your-convex-deployment>.convex.site/api/verify-key \ -H "Authorization: Bearer builder_..."GET /api/verify-key is the quickest way to confirm a key works: it returns the resolved workspaceId and the key's effective scopes.
/api/mcp) is served by the BuilderStudio app. The direct HTTP endpoints (/api/run, /api/canvases, /api/executions, /api/verify-key) are Convex HTTP-action routes served on your deployment's .convex.site host. The billing routes are reachable on both — the app proxies bearer-authenticated requests through to Convex.Was this page helpful?