Authentication
API Keys & OAuth
Create, manage, and rotate access credentials for StatusPool's monitoring APIs. Keep your integrations secure without sacrificing uptime visibility.
API Keys
Every StatusPool account comes with a default API key. You can generate up to three additional keys per account, each with granular scope controls.
1. Generate a Key
Navigate to Settings → API Access in your dashboard. Click Create API Key, give it a descriptive name like prod-monitoring-cli, and select the scopes you need: monitors:read, monitors:write, alerts:read, or teams:admin. Confirm with your account password and 2FA code.
2. Pass the Key in Headers
Include your key in the Authorization header on every request. StatusPool expects the Bearer scheme:
curl -X GET https://api.statuspool.io/v2/monitors \ -H "Authorization: Bearer sp_live_4f8a2c91e7d3b6..." \ -H "Content-Type: application/json"
Never embed keys in client-side JavaScript or public repositories. Use environment variables or a secrets manager.
3. Rotate Keys Regularly
StatusPool recommends rotating API keys every 90 days. In the API Access panel, create a new key with the same scopes, update your integrations, then revoke the old key immediately. Revoked keys are logged with a timestamp and the action is visible to all team admins in the audit trail.
Keys that have not been used in 60 days are flagged as stale in your dashboard. You will receive an email notification to the account owner before any automatic suspension.
Rate Limits by Key Tier
API keys inherit the rate limits of your plan. On the Team plan, each key allows up to 600 requests per minute for read endpoints and 120 requests per minute for write endpoints. The Enterprise plan raises these to 2,400 and 600 respectively. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.
OAuth 2.0 Flow
For third-party integrations and partner applications, StatusPool supports Authorization Code Grant with PKCE. This lets users authorize external tools without sharing their API keys.
Register Your Client
Go to Settings → OAuth Applications and click Register New Client. Provide your application name (e.g., PagerDuty Sync), a description, and a redirect URI such as https://hooks.internal.example.com/callback. You will receive a client_id and a client_secret — store the secret securely.
Authorization Endpoint
Direct users to StatusPool's authorization URL with your client parameters:
https://statuspool.io/oauth/authorize ?client_id=your_client_id &redirect_uri=https://hooks.internal.example.com/callback &response_type=code &scope=monitors:read alerts:read &state=csrf_token_xyz &code_challenge=... &code_challenge_method=S256
Token Exchange
After the user authorizes, StatusPool redirects back with a code. Exchange it for an access token at https://api.statuspool.io/oauth/token. Access tokens expire after 1 hour; refresh tokens are valid for 30 days. Include the access token as a Bearer credential in subsequent API calls, identical to API key usage.
Supported Scopes
monitors:read — List and view monitor status, uptime history, and incident logs.
monitors:write — Create, update, and delete monitors and check configurations.
alerts:read — Retrieve alert rules, notification channels, and dispatch history.
alerts:write — Modify alert thresholds and notification preferences.
teams:admin — Manage team members, roles, and billing details.
Applications should request only the scopes they genuinely need. Users can review and revoke OAuth grants at any time from Settings → Connected Applications.
Security Best Practices
Protect your monitoring infrastructure with these proven credential-management habits. StatusPool never stores plaintext keys and encrypts all tokens at rest using AES-256-GCM.
Least-Privilege Scopes
Assign only the permissions each key or OAuth client actually needs. A CI/CD pipeline that only reads monitor status should never hold monitors:write or teams:admin. Narrow scopes limit blast radius if a credential is compromised.
Environment Variables & Vaults
Store keys in environment variables, AWS Secrets Manager, HashiCorp Vault, or GitHub Secrets — never in source code, config files committed to Git, or build artifacts. Rotate keys immediately if you suspect accidental exposure.
IP Allowlisting
Enterprise accounts can restrict API keys to specific IP ranges. In the API Access panel, add CIDR blocks (e.g., 203.0.113.0/24) under IP Restrictions. Requests from outside these ranges receive a 403 Forbidden response.
Audit Trail
Every API key creation, rotation, and revocation is recorded in the audit log with the actor's email, timestamp, and source IP. Access the log at Settings → Audit Log or via the GET /v2/audit-log endpoint. Logs are retained for 365 days.
Monitor Key Usage
Enable Usage Alerts on each API key to receive an email when a key makes its first request, exceeds 80% of the rate limit, or is used from a new IP geolocation. This gives you early warning of anomalous patterns without disabling legitimate integrations.
Incident Response
If a key is compromised, revoke it instantly from the dashboard. All active sessions using that key terminate within 30 seconds. Generate a replacement key with the same scopes, deploy it to your systems, and review the audit log for any unauthorized requests made during the exposure window.