Create an API key
One GridRouter key reaches every vendor you have connected. Scope it, cap it, and keep a backup.
Before you start
Open Settings → API keys (/settings/keys) and choose Create key. The secret is shown
once; store it in your secret manager as GRID_API_KEY.
grid_live_<12-character lookup>_<32-character secret><6-character checksum>The checksum lets secret scanners and the gateway reject a mistyped key without a lookup.
grid_test_ keys reach sandbox vendors only, and grid_agent_ keys belong to an agent with its
own budget.
Scopes
A key can only do what its scopes allow. The dashboard offers three presets:
| Preset | Scopes |
|---|---|
| Backend app (default) | call, run, jobs, pipelines:run, catalog:read, balance:read |
| Read only | catalog:read, balance:read, logs:read, pipelines:read |
| Agent / MCP | the backend scopes plus lists, logs:read, pipelines:read |
A key never grants scopes its creator does not hold. * (full access, including future scopes) is
for owners only.
Limits on a key
- Expiry: never, or a date after which the key stops working.
- IP allowlist: up to 50 IPv4 or IPv6 addresses and CIDR ranges, matched against the
connecting IP.
A request from anywhere else fails with
403 scope_denied. - Credit limit: a cap on what the key spends on charged calls, reset daily, weekly, monthly
or never (
403 budget_blockedonce reached). Calls on your own vendor keys cost0and never count against it. - Label:
primary,backup,ci. Keep a backup key so rotating or revoking one never causes downtime.
Rotate mints a replacement with the same scopes and limits; the old key keeps working for a grace period (24 hours by default, 7 days at most). Revoke stops billable calls immediately.
The same operations are in the API: create, rotate, set a credit limit and revoke.