Authentication & regions

API keys

Every request to the REST API, the OpenAI-compatible endpoint, and (in the dev-only convenience path) MCP authenticates with a bearer API key, minted per workspace from Settings → API keys in the dashboard:

curl -s https://apibr.aize.dev/v1/query \
  -H "Authorization: Bearer $BRAIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "..."}'

• Keys are prefixed bzk_ — a human-recognizable marker, not a secret format detail you need to parse.
• A key is shown once, at creation. Store it in a secrets manager or environment variable, never in client-side code or a public repo.
• A missing, malformed, or revoked key returns a 401 RFC 9457 Problem with type: "https://braize.app/errors/unauthorized" — see Handling errors.
• Keys are workspace-scoped: a key only ever sees the workspace it was minted in. There is no cross-workspace key.

MCP authentication

The documented, production path for MCP is OAuth 2.1 / token exchange against the per-workspace MCP endpoint. A bearer bzk_ key is also accepted as a dev-only convenience, gated behind MCP_ALLOW_API_KEY — it is not the path to build a real integration against. See Setting up MCP.

Regions

A workspace is pinned to exactly one region at creation time — today eu-central-1 or me-central-1. That choice is enforced, not advisory: your data and the AI inference calls made on your behalf stay in that region, and Braize refuses an unsafe fallback rather than silently routing around the constraint. There is no self-serve way to move a workspace to a different region after creation (it requires an internal migration tool).

The REST API host is region-aware:

https://api.{region}.braize.app/v1

with {region} one of eu-central-1 | me-central-1. (The dashboard's own proxy host, apibr.aize.dev, routes to your workspace's region for you — use it unless you have a reason to hit a regional host directly.)

Pinning a contract version

Every response carries meta.braize_version (a date, e.g. 2026-09-01). The contract is additive-only forever, so upgrading is normally a no-op — but if you need to freeze behavior, send an explicit override:

curl -s https://apibr.aize.dev/v1/query \
  -H "Authorization: Bearer $BRAIZE_API_KEY" \
  -H "Braize-Version: 2026-09-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "..."}'

Omit the header to always get your workspace's currently pinned version.