---
title: Keys, scopes and rate limits
description: How API keys are issued and expire, what each scope grants, how tokens map to your data, the rate limits, and the 429 envelope.
canonical_url: "https://cascades.crscreditapi.com/docs/concepts/scopes-and-keys"
doc_version: "1.0.0"
last_updated: "2026-10-05T19:24:37Z"
source: docs/concepts/scopes-and-keys.md
---

# Keys, scopes and rate limits

## How do I get a key?

Mint one at [/api-keys](/api-keys) with **Generate key**. The raw token is a 36-character UUID (for example `3fa85f64-5717-4562-b3fc-2c963f66afa6`) and is shown **once**; Cascades stores only a SHA-256 digest and the first eight characters (the *prefix*, used for rate limiting and in logs). Keys expire after **90 days** by default. **Regenerate key** on the same page revokes your current key and shows a new one, so your account holds one key at a time; revoking from that page invalidates your keys at once.

Send the key as a bearer token:

```http
Authorization: Bearer {{API_KEY}}
```

A missing, malformed, expired or revoked token returns `401 unauthorized` with a `WWW-Authenticate: Bearer` challenge. Repeatedly presenting unknown tokens gets the source IP banned for a while.

## What does a key see?

A key belongs to an **API client**, which belongs to a **user**. That chain decides visibility:

- **Cascades and templates are user-level.** Every client of the same user sees the same cascades.
- **Executions, batches, webhook subscriptions and deliveries are client-level.** Two clients of one user cannot read each other's runs or subscriptions.

Requests for a record you cannot see return `404 not_found` — the API never confirms that another tenant's id exists.

## Which scopes exist?

| Scope | Grants |
|---|---|
| `workflows:read` | `GET /workflows`, `GET /workflows/{id}`, `GET /workflows/{id}/test_cases` |
| `workflows:write` | Create, update, delete and generate cascades |
| `workflow_templates:read` | The template catalog |
| `executions:read` | List and show executions and batches, review events, artifact **lists** |
| `executions:read:full` | Adds `step_outputs` and `failed_steps` to execution detail, and unlocks artifact **downloads** and batch exports — routinely contains SSNs, dates of birth, addresses and raw vendor responses |
| `executions:write` | Trigger, cancel, re-evaluate, batches, review decisions, assignment, notes, bulk actions |
| `webhooks:read` | List and show subscriptions and deliveries |
| `webhooks:write` | Create, update, delete subscriptions, rotate secrets, retry deliveries |

Keys minted at [/api-keys](/api-keys) carry all eight. A request that needs a scope the key lacks returns `403 insufficient_scope` with the missing scope in `details`. Request the narrowest set your integration needs when CRS issues production keys; in particular, ask for `executions:read:full` only when your flow handles per-step PII appropriately.

## What are the rate limits?

| Limit | Scope |
|---|---|
| 60 requests / minute | per source IP, on `/api/v1/*` |
| 600 requests / hour | per token prefix |
| 300 requests / 5 minutes | per source IP, across the whole host |

A throttled request answers `429` with the standard error envelope and a `Retry-After` header. The message is fixed; the number of seconds until the window resets is only in the header, so read `Retry-After`, never the message:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json; charset=utf-8
```

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry later.",
    "details": [],
    "request_id": "7d4c2f48-…",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/rate_limited"
  }
}
```

Honour `Retry-After`; when it is absent, back off exponentially from one second. Prefer webhooks over tight polling loops, and batches over hundreds of single triggers.

## Keys used on these docs

When you are signed in, the key filled into the samples here is a separate, one-hour, **sandbox-only** token minted for the docs Try-it console. It cannot make live requests even on an approved account, and it is not the key to ship in your integration.

## Related

- [Sandbox vs live](/docs/concepts/sandbox-vs-live)
- [Errors](/docs/api/errors) — every code with causes and fixes
- [`GET /workflows`](/docs/api/workflows/list-workflows)

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.