API keys: scopes, restrictions, rotation and policy
Creating scoped keys, the full scope list, live vs test keys, environment and IP restrictions, expiry, rotation with a grace period, and the organization API policy.
Create keys under Developer API → API keys (owner or admin; the organization policy can also allow members to create their own). The secret is shown once. A key is owned either by the user who created it or by a service account.
Scopes
A key can do only what its scopes allow; the UI groups them by resource. The complete vocabulary:
| Resource | Scopes |
|---|---|
| Monitors | monitors:read monitors:create monitors:update monitors:enable monitors:disable monitors:delete |
| Results & detections | results:read incidents:read anomalies:read intelligence:read |
| Fleet | agents:read agents:manage |
| Notifications | notification_rules:read|create|update|delete webhooks:read|create|update|delete |
| Maintenance | maintenance_windows:read|create|update|delete |
| Organization | organization:read |
Key type, expiry and restrictions
- Live (
pt_live_) or test (pt_test_) — the type is visible in the prefix so a test key in production is obvious. - Expiration — 30, 90, 180 days, 1 year, a custom date, or never (if the policy allows it).
- Allowed environments — restrict the key to monitors whose
environmentisdevelopment,stagingand/orproduction; leave all unchecked to allow every environment. - IP restrictions — one IP or CIDR per line; requests from elsewhere get
IP_NOT_ALLOWED. - Rate limits — per-key read / write / delete per minute, within the organization ceilings.
Rotation
POST /api/v1/auth/organization/api-keys/{id}/rotate issues a new secret and keeps the old one working for a grace period of 1h, 6h, 24h or 7d so deployments can roll. The key records rotated_at, rotated_from / rotated_to and grace_period_ends_at. Revoke immediately with POST …/{id}/revoke. Every key also tracks last_used_at, last_used_ip and failed_auth_attempts.
Organization API policy
Developer API → API policy sets the rules every key must satisfy. Defaults: API enabled; user-owned keys allowed; expiration not required; maximum lifetime 365 days; never-expiring keys allowed; production not restricted to service accounts; IP restrictions allowed; rate-limit ceilings 500 / 100 / 20 per minute. Turning Allow API keys off blocks every key at once without revoking them.
Usage per key — requests, errors, last seen — is on Developer API → Usage, backed by the API request log, which is retained according to the plan's audit retention.