Guides

API Keys

View as Markdown

An API key (rsk_...) is how your applications authenticate to MeshAPI. It is also the unit that carries limits, spend caps, model access, and usage attribution — so managing keys is how you control what each application is allowed to do.

This page covers the key-management API. For using a key to authenticate a request, see Authentication.

Key management uses a user JWT — your dashboard session token — not an rsk_ key. An inference key cannot create or modify keys, by design: a leaked key must not be able to mint more.

Creating a key

$curl https://api.meshapi.ai/v1/keys \
>  -H "Authorization: Bearer <YOUR_USER_JWT>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "label": "production-web",
>    "rpm": 300,
>    "spend_cap_usd": "50.00",
>    "allowed_models": ["openai/gpt-4o-mini", "anthropic/claude-sonnet-4-5"]
>  }'

The plaintext key is returned once, in the key field of the create response, and is never retrievable again — only a hash is stored. Capture it at creation or you will have to issue a new one.

Fields

FieldPurpose
labelHuman name shown in the dashboard and usage breakdowns
default_modelModel used when a request omits model
rpm / rpd / tpmRate limits — see Rate Limits & Spend Caps
spend_cap_usdCumulative USD ceiling for this key
allowed_modelsAllow-list of models this key may call
model_limitsPer-model overrides
org_id / team_idAttach the key to an org or team for pooled billing and limits
routing_policy / routing_policy_template_idRetry and fallback behaviour (mutually exclusive — sending both is a 422)

rpm above 1,000 or rpd above 1,000,000 are rejected with 422.

Managing keys

OperationEndpoint
List keysGET /v1/keys
Filter options for the listGET /v1/keys/filter-options
Update a keyPATCH /v1/keys/{id}
Suspend a keyDELETE /v1/keys/{id}
Resolved effective limitsGET /v1/keys/{id}/limits

DELETE is a soft delete: it sets the key’s status to suspended. The key stops working at the inference layer immediately, but the record and its usage history are preserved. There is no hard-delete endpoint — this keeps historical usage attributable.

Model allow-lists

allowed_models restricts a key to a named set of models. It is the cleanest way to stop a cheap application reaching an expensive model.

An allow-list silently breaks features that route to models you didn’t list:

  • model: "auto" — the Auto Router picks from your allow-list. If none of its candidates are listed, routing fails.
  • Web search — /v1/web/search checks against its own model pin. An allow-list that omits it disables web search for that key.

Neither failure is obvious from the error. If a feature stops working right after you set an allow-list, this is why. Include the models those features depend on, or leave the key unrestricted.

Org and team keys

Assigning org_id or team_id makes a key part of a shared structure: it draws on the org’s shared balance and inherits the org’s and team’s limits, resolved minimum-wins alongside the key’s own.

Attaching a routing_policy_template_id requires the key to belong to an org — templates are org-scoped, and a key with no org gets a 422.

See Organizations & Teams for the surrounding model.