Fresh 2026

Management API keys

Create and administer your org's API keys programmatically with management keys, set per-key spend limits, and track usage per key.

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:

Can	Cannot
Create, list, update, and delete that org's API keys	Call the gateway, since it is not a model-calling key
Read per-key usage and spend	Touch another organization's keys
Set and change per-key spend limits	Create other management keys, which is dashboard only

A management key returns 401 if used against the model endpoints. Keep it server-side, treat it like any other secret, and rotate it if it leaks.

---

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_

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_" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-acme",
    "limit": 50,
    "limit_reset": "monthly"
  }'

import requests

resp = requests.post(
    "https://gateway.merge.dev/v1/keys",
    headers={"Authorization": "Bearer mgmt_"},
    json={"name": "customer-acme", "limit": 50, "limit_reset": "monthly"},
)
key = resp.json()
# Store key["key"] now. It is the only time the raw key is returned.
print(key["key"])

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

{
  "hash": "a1b2c3d4...",
  "name": "customer-acme",
  "label": "mg_8Kx2pQ",
  "disabled": false,
  "limit": 50,
  "limit_reset": "monthly",
  "usage": 0,
  "limit_remaining": 50,
  "created_at": "2026-06-02T17:04:00Z",
  "key": "mg_8Kx2pQrS..."
}

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_"

import requests

keys = requests.get(
    "https://gateway.merge.dev/v1/keys",
    headers={"Authorization": "Bearer mgmt_"},
).json()

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_" \
  -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_"

import requests

base = "https://gateway.merge.dev/v1/keys/a1b2c3d4"
headers = {"Authorization": "Bearer mgmt_"}

requests.patch(base, headers=headers, json={"disabled": True, "limit": 100})
requests.delete(base, headers=headers)

Deleting a key revokes it immediately but keeps its historical spend, so it still appears in usage reporting. To stop a key from being used without losing it, set disabled: true instead.

---

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.

Name keys when you create them, for example customer-acme or alice@acme.com. The usage view and key list show the name, which makes per-customer and per-employee tracking readable at a glance.

---

Next steps

Org and project budgets, the unified billing dashboard, and how routing and compression cut costs

Segment spend and apply budgets and routing per team, product, or environment