API Keys

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 takes an admin key (mak_...), not an rsk_ key. An inference key cannot create or modify keys, by design: a leaked key must not be able to mint more.

Create an admin key in Dashboard → Settings → Admin keys. It is shown once, carries an explicit permission set, and always expires. See Admin Keys for permissions, scopes, rotation, and revocation. Everything on this page is also available in Dashboard → API Keys without any credential; the API is for automating it.

Creating a key

curl https://api.meshapi.ai/v1/keys \
  -H "Authorization: Bearer $MESH_ADMIN_KEY" \
  -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

Field	Purpose
`label`	Human name shown in the dashboard and usage breakdowns
`default_model`	Model used when a request omits `model`
`rpm` / `rpd` / `tpm`	Rate limits — see Rate Limits & Spend Caps
`spend_cap_usd`	Cumulative USD ceiling for this key
`allowed_models`	Allow-list of models this key may call: exact IDs or a brand wildcard such as `openai/*`, up to 200 entries
`blocked_models`	Models this key may not call, in the same format. Applied after `allowed_models`; a block always wins
`model_limits`	Per-model lifetime budgets: `max_cost_usd`, `max_tokens`, `max_requests` per model ID
`fixed_provider`	Serve this key only from the named provider. No cross-provider fallback, and a model that provider cannot serve is a `400`
`pii_policy`	The key’s PII redaction policy (`{"enabled": true, ...}`), masking matched categories before the request reaches the model. Omit to inherit the org default; `{"enabled": false}` exempts the key
`body_log_policy`	Keep this key’s request and response bodies readable on `GET /v1/usage/requests/{request_id}`. Omit to inherit the org default; refused with `422` while the org has zero data retention on
`org_id` / `team_id`	Attach the key to an org or team for pooled billing and limits
`routing_policy` / `routing_policy_template_id`	Retry and fallback behaviour (mutually exclusive — sending both is a `422`)

rpm or rpd above your organization’s rate-limit tier ceiling (1,000 RPM and 1,000,000 RPD on the standard tier) are rejected with 422. See Rate Limits & Spend Caps. A key created with an admin key carries every API scope except files:read and files:write, so it gets 403 on the Files & RAG routes. Create keys that need RAG in Dashboard → API Keys.

Managing keys

Operation	Endpoint
List keys	`GET /v1/keys`
Filter options for the list	`GET /v1/keys/filter-options`
Update a key	`PATCH /v1/keys/{id}`
Suspend a key	`DELETE /v1/keys/{id}`
Resolved effective limits	`GET /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.

Pinning the API version

A key can carry an api_version — the dated contract every request made with it receives, unless the request sends its own X-Mesh-Version header. Useful when the calling code is not yours to change, or when a whole integration should sit on one version.

curl -X PATCH https://api.meshapi.ai/v1/keys/{id} \
  -H "Authorization: Bearer $MESH_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_version": "2026-08"}'

Send null to clear it. In the dashboard it is the key’s API Version field. See API versioning for what a version covers and which ones are served.

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.

The failure is not 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.

Authentication — rsk_ vs mak_, and using a key to make requests
Admin Keys — the mak_ credential this page’s API takes
Rate Limits & Spend Caps — how limits resolve across tiers
API Versioning — pinning a key to a dated contract
Organizations & Teams — shared billing and pooled limits
Account Configuration Checklist — recommended setup pass

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh Code

Mesh CLI

Platform

Reference

Creating a key

Fields

Managing keys

Pinning the API version

Model allow-lists

Org and team keys

​Creating a key

​Fields

​Managing keys

​Pinning the API version

​Model allow-lists

​Org and team keys

​Related

Creating a key

Fields

Managing keys

Pinning the API version

Model allow-lists

Org and team keys

Related