Skip to main content

​
What this is for

API keys authenticate your applications when they call the gateway. Each key carries its own permissions, rate limits, optional budget, and an optional MCP scope. Keys are managed in Configuration → API Keys and are pushed to the connected gateway after creation. The page has two tabs: Human, the keys your team creates by hand — everything below describes these — and System-managed, the keys Guardway created for machines running the agent. See System-managed keys. Use one key per application or environment so you can rotate, scope, and revoke them independently. The dashboard tracks status (active, inactive, expired, revoked), last-used time, request counts, and rate-limit usage for each key.

​
Options

Click Create Key to open the Create API key dialog. It walks through Identity, Limits, Access (Providers & MCP), and Copy. In a key’s edit panel you can change its Key name and Application (Identity), its Rate limit (requests / min) (Limits), and its Allowed providers, Allowed models, and MCP access. Expiration, Tokens / min, and the budget are set at creation.

​
Key settings

IP allowlist (optional) and Metadata (JSON), under Advanced settings on the Access step, are not saved with the key yet. Whatever you enter there, the key is not restricted by IP.

​
MCP access

Scope the key to specific MCP servers and tools. A key can be MCP-only: switch every provider off while MCP enabled is on (with no provider configured, turn off LLM access instead). It can then reach MCP servers only. Gateway v0.5.40 and later refuse it on every LLM endpoint; older gateways refuse it on the main inference endpoints only, and the Responses WebSocket (GET /v1/responses), files, batches, fine-tuning, vector stores, and assistants still accept it. The key’s detail panel shows None: MCP-only key under Providers. Tools a key may not use are left out of the client’s tool list, and calls to them are refused. See Give each team its own set of tools for a worked example.
Per-tool switches are enforced by gateway v0.5.39 and later. On older gateways, only the server-level settings apply; use an application policy for tool-level rules. From gateway v0.5.41, a key’s rules also accept a server’s name in another case or its slug, but in Allowed servers such an entry grants access only if it matches no other server.

​
How to configure

Create API key dialog

Configuration → API Keys

1

Open Configuration → API Keys

Open Configuration → API Keys from the dashboard sidebar and click Create Key.
2

Name the key

On the Identity step, set a Key name and choose an Expiration. If you use applications, pick one under Application to apply its policy to the key. Only the name is required: click Next to set limits and access, or Create key to create it now.
3

Set limits

On the Limits step, set Requests / min and Tokens / min, and optionally a Budget ($) with Budget alert thresholds (%).
4

(Optional) Restrict access

On the Access step, switch off Allowed providers this key should not reach, and select Allowed models to limit it to specific models. Use the MCP settings to scope MCP servers and tools. To make the key MCP-only, switch every provider off and leave MCP enabled on; with no provider configured, turn off LLM access instead. See MCP access.
5

Create and copy the secret

Click Create key. The full secret is shown once. Copy it into your secrets manager immediately.
The secret value is shown once at creation. If you lose it, you must rotate the key.
6

Verify it pushed to the gateway

The new key appears in the list with status Active. Run a test call from Playground with this key to confirm it reached the connected gateway.
API keys list

API keys list

​
Status, rotate, revoke

  • Active / Inactive — toggle a key on or off without rotating its secret.
  • Rotate issues a new secret. The old secret stops working immediately, so plan a deploy window for any client that uses it.
  • Revoke disables the key permanently and clears its in-flight quota.
Every status change, rotation, and revocation is recorded in the Audit log.

​
System-managed keys

The System-managed tab lists the keys Guardway created for endpoint machines — one per machine, created automatically at the machine’s first check-in — grouped by the Access Profile each one follows. Keys created before profiles existed, or whose machine has not checked in since a profile was assigned, appear under Unprofiled. These keys are view and revoke only. There is no edit form for them on purpose: each machine re-applies its profile every time it checks in, so a hand-edit would silently revert at that machine’s next policy refresh. To change what a machine’s key may do — which models, what rate, what budget, when it expires — change its Access Profile instead. Revoking a system-managed key takes effect immediately. An active machine then creates a fresh key at its next check-in: same profile, new secret. See Revocation and re-mint.
  • Providers — connect the upstream LLM providers a key can call.
  • Access Profiles — the limits every endpoint machine’s key inherits, set once per policy.
  • Models — control which provider models are enabled.
  • MCP — register MCP servers and connect clients.
  • Security — guardrail policies enforced for every key.
  • Budgets and Alerts — per-key, application, and team budgets compared, and the alerts each sends.
  • Notifications — subscribe to budget alerts.