Customer API keys

A customer API key is a Gateway key bound to one customer, so its requests need no customer field. Give one to each tenant so a leaked key exposes only that tenant.

Mint a key

POST /v1/customers/{customer_id}/api-keys with your organization-level key. The raw key comes back once, in key.

cURL

curl -X POST https://api-gateway.merge.dev/v1/customers/{customer_id}/api-keys \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme production", "spending_limit": 100, "reset_period": "monthly" }'

A customer can hold 5 keys; a sixth returns 409 customer_api_key_limit_reached, and minting for an inactive customer returns 400 customer_inactive. GET on the same path lists keys without secrets. The customer then calls Gateway as usual:

cURL

curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer $CUSTOMER_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "input": [{"type": "message", "role": "user", "content": "Hello"}]
  }'

A customer value that contradicts the key returns 400 customer_mismatch.

Rotate or revoke a key

To rotate without downtime, mint a new key, move the customer onto it, then revoke the old one with DELETE /v1/customers/{customer_id}/api-keys/{key_id}. Deleting a customer revokes its keys; deactivating it makes them return 403 until reactivated.

What a customer key can reach

Other customers’ paths return 404, so tenants can’t discover each other, and organization-level routes return 403 customer_scoped_key_forbidden.

Allowed for its own customer	Not allowed
Read the customer, budget, routing policies, allowed models, and controls	List or create customers, or read organization-wide usage
Change the customer’s `name`	Change its key usage mode or status
Create, update, and delete routing policies	Create, change, or delete its budget
Add, rotate, and delete its own vendor keys	Delete the customer, or list or mint API keys
Read its usage	Read or change guardrails, or call the Evals API

Its usage shows only customer_byok_spend and request_count, and its key list only the customer’s own vendor keys, hiding what you pay and which keys you hold.

Reference

Field	Type	Description
`id`	string	Key identifier. Pass to `DELETE`.
`key`	string	The raw key, on create only
`customer`	UUID	The customer the key is bound to. Can’t be changed.
`name`	string	Your label
`key_prefix`	string	The first 10 characters, for recognizing the key in a list
`is_active`	boolean	Whether the key can authenticate
`spending_limit`	number	USD cap for this key over `reset_period`. Applies on top of the customer’s budget.
`reset_period`	enum	`daily`, `weekly`, or `monthly` (lowercase, unlike budgets). Requires `spending_limit`.
`rate_limit_rpm`	integer	Requests per minute, unset for no limit. Counted against all of your organization’s traffic, not only this key’s.
`created_at`, `expires_at`	datetime	Timestamps

Next steps

Budgets

Cap the customer’s total spend

Guardrails

Let a key-pinned customer run its own guardrail policy