Concepts
Keys, scopes and rate limits
How API keys are issued and expire, what each scope grants, how tokens map to your data, the rate limits, and the 429 envelope.
How do I get a key?
Mint one at /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:
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 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/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json; charset=utf-8{
"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
- Errors — every code with causes and fixes
GET /workflows