Management API keys
The Management API issues, rotates, restricts, and caps your organization’s API keys from code, such as one key per customer or employee. It authenticates with a management key that can never make model calls.
Management keys
Create management keys under API keys → Management keys in the dashboard, the only place they’re made. The raw mgmt_ key is shown once, acts on one organization, returns 401 on model endpoints, and should stay server-side.
A new management key gets the dashboard permissions its creator holds, so it can do through the API what that person can do in the dashboard. Scopes are those permission names. A key keeps the scopes it was minted with: if your permissions change, mint a new key. These scopes cover the keys API:
Keys minted before scopes became permission names hold manage_keys and read_usage, which still work as manage_api_keys and view_billing. The other areas of the API use their own dashboard permissions; see scopes.
Send it to https://api-gateway.merge.dev as Authorization: Bearer mgmt_....
Create a key
POST /v1/keys returns 201 with the raw mg_ key, exactly once. All body fields are optional.
Creation returns 403 payment_method_required when your organization has no payment method on file, except on the Free plan, and 409 org_api_key_limit_reached once the organization holds 1,000 keys.
The response is a key object plus key. hash is the key’s ID for every other call: the SHA-256 hash of the raw key as 64 hex characters, safe to log.
usage is the USD spend in the current limit_reset window. usage_daily, usage_weekly, and usage_monthly are the spend today, since Monday, and since the 1st of the month (UTC), whatever the window. Each byok_usage field is the part of the matching usage field that ran on your own provider credentials. creator_user_id is null for keys created through the Management API.
Manage keys
On PATCH, omitted fields are left alone. null removes the limit ("limit": null), the allowlist, the routing policy binding, or the expiry. project_id returns 400, since a key’s project can’t change. Pause a key with "disabled": true. Full schemas: API reference.
Restrict which models a key can call
allowed_models limits a key you hand to a team or customer to listed models.
Pinning a disallowed model returns 403 model_not_allowed. Under a routing policy, the allowlist filters candidates instead, failing only when none is allowed. It applies on every endpoint, alongside your organization’s blocklist.
Bind a routing policy to a key
routing_policy_id gives one key its own routing without a project or per-request field. Rebinding needs no rotation; null unbinds.
A policy named on the request beats the binding, which beats customer, project, and organization defaults (precedence). POST /v1/embeddings ignores bindings.
Per-key spend limits
A key with limit and limit_reset returns 402 api_key_limit_exceeded once the current window’s spend reaches the limit. Windows reset at midnight UTC (weekly on Monday, monthly on the 1st). Each key object reports the window’s usage and limit_remaining for showing a customer their balance. See how this combines with other scopes in Budgets.
Per-key usage
Usage & spend → By attribution → API key lists each key’s requests, tokens, and spend. Management API keys record no creating user, so give each a descriptive name, such as customer-acme or alice@acme.com.