Embedded Routing

Customer keys

Give a customer its own BYOK provider key

A customer key is a customer’s own bring-your-own-key (BYOK) provider credential. When set, it overrides your organization’s key for that vendor on that customer’s requests.

Not to be confused with Customer API keys, which are Merge Gateway keys you give to a customer. The keys on this page are provider credentials you hold for them.

Path: /v1/customers/{customer_id}/keys. A GET lists the customer’s usable key per vendor, omitting vendors with no usable key under the customer’s key usage mode. A POST adds a customer key, overriding that vendor to CUSTOMER.

Key usage modes

Which credential serves a customer’s request depends on the customer’s key_usage_default, which you set on the customer or inherit from your organization’s default:

ModeResolution for a vendor
USE_ANYThe customer’s own key, else your organization’s key, else Merge-managed credentials
PREFER_BYOKPrefer a bring-your-own key, the customer’s or your organization’s, and fall back to Merge-managed credentials
BYOK_ONLYThe customer’s own key, else your organization’s key. Merge-managed credentials never serve
CUSTOMER_ONLYThe customer’s own key only. Neither your organization’s key nor Merge-managed credentials serve

The last two fail closed. A vendor the customer has not keyed comes back with key_ownership: null under CUSTOMER_ONLY, and a request routed to it returns 404 provider_credentials_missing. Under CUSTOMER_ONLY the fix is a key for that customer, since adding an organization key does nothing.

CUSTOMER_ONLY is what to reach for when each tenant must run strictly on its own provider account, with no shared capacity of yours behind it.

Fields

FieldDescriptionType
idMerge UUIDstring
vendorProvider slug, e.g. openaistring
key_ownershipThe resolved key’s owner: CUSTOMER, ORGANIZATION, or MERGEenum
created_at, modified_atTimestampsdatetime

Add a provider key

Pass the vendor as its slug (openai, anthropic), not its display name. Sending a display name that isn’t a known slug returns 400.

cURL
$curl -X POST https://api-gateway.merge.dev/v1/customers/{customer_id}/keys \
>  -H "Authorization: Bearer mg_<your_production_key>" \
>  -H "Content-Type: application/json" \
>  -d '{ "vendor": "openai", "api_key": "sk-..." }'