REST API
Authentication
How to authenticate Brunel API calls with a bearer API key, read-only versus read-write keys, IP restrictions, team policies, and what keys can never do.
Bearer keys
Every request carries a key in the Authorization header:
http
Authorization: Bearer brn_w_Q2m9x3…Create keys in Platform → API keys. See API keys for scopes, expiry, IP allowlists and rotation.
| Situation | Status | Code |
|---|---|---|
| No key | 401 | auth_required |
| Wrong, revoked or expired key | 401 | invalid_api_key |
| A read-only key calls an endpoint that writes | 403 | read_only_key |
| The key's IP allowlist excludes this address | 403 | ip_not_allowed |
| Your team's restricted access refuses this address | 403 | policy_denied |
| The action needs the browser session | 403 | browser_only |
Read-only and read-write
| Key | Can |
|---|---|
brn_r_… | GET endpoints and read-only MCP tools: account, projects, architectures, files |
brn_w_… | Everything above, plus analyze, design and refine |
The key acts as you
A key has your plan, your quotas and your projects. Calls count against the same monthly quotas as the app. If you are in a team with restricted access, its IP allowlist applies to your keys too, and Sign every member out revokes them.
Browser-only actions
Keys cannot manage keys, the account, billing, team security or members, company verification or sign-in. Those actions need the browser session, with a recent sign-in.
Keep keys secret
- Store keys in your CI secrets or your agent's secure configuration, never in code.
- The
api.brunel.cloudhost accepts keys only: it ignores cookies, so a browser session can never act there, and it allows calls from any origin without credentials.