Management API keys

The Management API lets you create and administer your organization’s API keys programmatically, instead of clicking through the dashboard. Use it to issue a unique key for each customer or employee, rotate keys on a schedule, cap spend per key, and track usage per key. It is authenticated by a separate management key, so the credential that provisions keys is never one that can make model calls.

Management keys

A management key is a provisioning credential. It authenticates the Management API and nothing else.

Create one in the dashboard under Settings → API keys → Management keys. The raw key (prefixed mgmt_) is shown once at creation, so copy it then. Only a hash is stored, so it cannot be retrieved later.

A management key is scoped to one organization:

The keys API

All Management API requests are relative to:

https://gateway.merge.dev

Authenticate with the management key as a bearer token on every request:

Authorization: Bearer mgmt_<your_management_key>

Create a key

POST /v1/keys mints a new API key and returns the raw key (prefixed mg_) exactly once. Pass an optional limit in USD and a limit_reset window to attach a spend cap.

$
curl -X POST https://gateway.merge.dev/v1/keys \
>
  -H "Authorization: Bearer mgmt_<your_management_key>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "customer-acme",
>
    "limit": 50,
>
    "limit_reset": "monthly"
>
  }'

The response is a key object. key is present only on creation:

1
{
2
  "hash": "a1b2c3d4...",
3
  "name": "customer-acme",
4
  "label": "mg_8Kx2pQ",
5
  "disabled": false,
6
  "limit": 50,
7
  "limit_reset": "monthly",
8
  "usage": 0,
9
  "limit_remaining": 50,
10
  "created_at": "2026-06-02T17:04:00Z",
11
  "key": "mg_8Kx2pQrS..."
12
}

hash is the stable identifier you use in every other call. It is a one-way hash, not the secret, so it is safe to store and log.

List keys

GET /v1/keys returns the org’s keys with current usage. It supports offset and limit query parameters, up to 100 keys per page.

$
curl https://gateway.merge.dev/v1/keys \
>
  -H "Authorization: Bearer mgmt_<your_management_key>"

Get, update, or delete a key

Address a single key by its hash:

• GET /v1/keys/{hash} returns one key with its usage
• PATCH /v1/keys/{hash} updates name, disabled, limit, or limit_reset
• DELETE /v1/keys/{hash} revokes the key

$
# Disable a key and raise its monthly limit
$
curl -X PATCH https://gateway.merge.dev/v1/keys/a1b2c3d4 \
>
  -H "Authorization: Bearer mgmt_<your_management_key>" \
>
  -H "Content-Type: application/json" \
>
  -d '{"disabled": true, "limit": 100}'
$
$
# Revoke a key
$
curl -X DELETE https://gateway.merge.dev/v1/keys/a1b2c3d4 \
>
  -H "Authorization: Bearer mgmt_<your_management_key>"

Per-key spend limits

Attach a budget to any key with limit, a dollar amount, and limit_reset, one of daily, weekly, or monthly. The gateway sums the key’s spend over the current window and rejects requests with HTTP 402 once the cap is reached. The window resets at midnight UTC.

Every key object reports usage, the spend in the current window, and limit_remaining, so you can show a customer their remaining balance or alert before they hit the cap. You can also set a spend limit when creating a key in the dashboard. For org-wide and project-level budgets, see Cost governance and savings.

Per-key usage and spend

Spend is tracked per key, which is effectively per customer or per employee since each key records who created it. The By API key tab in Usage & spend lists each key’s requests, tokens, and spend, and a per-key detail view breaks spend down by model, provider, and project.

Next steps