# Create an API key (/docs/getting-started/api-keys)



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`.

```text
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 [#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 [#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_blocked` once reached). Calls on your own vendor keys cost `0` and 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](/docs/api/access/keys_create),
[rotate](/docs/api/access/keys_rotate), [set a credit limit](/docs/api/access/keys_limit_set) and
[revoke](/docs/api/access/keys_revoke).