Skip to main content
Majordomo API keys (mdm_sk_...) authenticate requests through the gateway. Every proxied request must include a valid key in the X-Majordomo-Key header. Usage is tracked per key.

​
Managing keys in the dashboard

Create, revoke, and monitor keys from the API Keys section of the Majordomo dashboard. The dashboard shows per-key request counts, costs, and last-used timestamps. The plaintext key is shown once at creation time. Store it in your secrets manager (AWS Secrets Manager, 1Password, GitHub Secrets, etc.).

​
Managing keys via CLI

​
Using keys in requests

Pass the key in the X-Majordomo-Key header on every request:
Keys are validated on every request. Invalid or revoked keys return 401 Unauthorized.

​
Per-key settings

Each key carries a few settings that change how the gateway handles its traffic. All are editable from the key’s detail page in the dashboard; credential_mode can also be chosen when you create the key.

​
Credential mode

Routing has to authenticate against whichever provider it selects, so this setting decides whose credentials it may use:
  • byok restricts routing to providers you have stored a key for. This is the default, and it is what every key did before the setting existed.
  • majordomo restricts routing to providers Majordomo holds a key for, so you need no provider accounts of your own.
  • prefer_own uses your key for each provider you have one for and ours for the rest, then still picks on cost across the combined set.
It applies only to requests that opt into routing. Traffic pinned to a concrete provider always uses the Authorization header you send. See Provider Routing.

​
Deprecated model behavior

passthrough forwards the request unchanged and lets the provider reject it. redirect silently substitutes the recommended replacement. warn substitutes the replacement and adds X-Majordomo-Deprecated-Model and X-Majordomo-Deprecated-Replacement to the response, so you can find the callers still using the old model and fix them.

​
Data policy floors

require_zdr and require_no_data_collection restrict which endpoints routing may pick. They are floors rather than fixed values: a request can tighten them with the data policy headers but cannot relax them. Setting require_zdr on a key means no request on that key ever reaches a non-ZDR endpoint, whatever headers it sends.

​
Key strategy

Use separate keys for separate concerns: This gives you cost and usage breakdowns per environment or team member in the dashboard without any additional configuration.