Authentication — API Keys & OAuth
Zero-downtime reliability for modern cloud apps
Getting Started
Secure Access for Every Integration
StatusPulse supports two authentication methods: API keys for server-to-server automation and OAuth 2.0 for third-party integrations that need delegated user access. Choose the method that matches your use case, and always follow the principle of least privilege when assigning scopes.
All API requests must include your credentials in the Authorization header. The base endpoint for every operation is https://api.statuspulse.io/v1. Unauthenticated requests return 401 Unauthorized. Expired or revoked credentials return 403 Forbidden.
api-keys
Generating & Managing API Keys
API keys are the simplest way to authenticate scripts, CI/CD pipelines, and internal tooling against the StatusPulse platform. Each key is scoped to a specific workspace and can be restricted to read-only or read-write access.
Create a New Key
Navigate to Settings → API Keys in your workspace dashboard. Click Generate Key, assign a descriptive label (e.g., deploy-pipeline-prod), and select the desired scope set. The full key — prefixed with sp_live_ for production or sp_test_ for sandbox — is displayed once. Store it in a secrets manager such as HashiCorp Vault, AWS Secrets Manager, or 1Password CLI.
Rotate Keys Safely
StatusPulse allows two active keys per scope set. Generate a replacement key before revoking the existing one to avoid gaps in automated checks. After rotation, update your environment variables and verify connectivity with a GET /v1/me call. Keys are automatically disabled after 365 days; set calendar reminders or use Terraform to enforce rotation cadences.
Rate Limits & Best Practices
Production keys are limited to 1,200 requests per minute per workspace. Sandbox keys cap at 120 requests per minute. Never embed keys in client-side JavaScript, public repositories, or webhook payload bodies. Use the X-Request-ID header on every call so our support team can trace anomalies in your account under ticket SLA-4892.
oauth2
OAuth 2.0 Setup for Third-Party Integrations
OAuth 2.0 is required when building integrations that act on behalf of StatusPulse users — for example, a custom dashboard app, a partner monitoring plugin, or a Slack bot that posts incident summaries to a dedicated channel. The platform implements the Authorization Code flow with PKCE support.
Register an OAuth Application
Go to Settings → OAuth Applications and click Register New Application. Provide a name (e.g., PagerDuty Incident Sync), a description, and one or more redirect URIs such as https://hooks.yourcompany.com/statuspulse/callback. You will receive a Client ID and a Client Secret. The secret is shown once; download it to a secure location immediately.
Authorization Endpoint
Direct users to https://auth.statuspulse.io/oauth/authorize with your client_id, redirect_uri, response_type=code, a scope parameter, and a state token for CSRF protection. After consent, StatusPulse redirects back with an authorization code valid for 10 minutes. Exchange it at https://auth.statuspulse.io/oauth/token using your client credentials to obtain an access token (valid 1 hour) and a refresh token (valid 90 days).
Token Refresh & Revocation
Use the refresh token to obtain a new access token without re-prompting the user. Call POST /oauth/token with grant_type=refresh_token and your stored refresh token. Users can revoke your application's access at any time from Settings → Connected Apps. When a token is revoked, subsequent API calls return 401 with an X-Error: token_revoked header so your integration can gracefully disconnect.
scopes
Managing Scopes & Permissions
Scopes define exactly which resources your API key or OAuth application can access. StatusPulse uses a fine-grained scope model so you never grant more permissions than necessary. Every key and OAuth client must declare its scopes at creation time; scopes cannot be expanded later without generating a new credential.
Available Scopes
checks:read — List and view uptime checks, response times, and historical data.
checks:write — Create, update, pause, and delete checks.
incidents:read — Retrieve incident timelines, root-cause notes, and resolution timestamps.
incidents:write — Acknowledge incidents, add annotations, and close resolved events.
webhooks:read — View configured webhook endpoints and delivery logs.
webhooks:write — Add, modify, and remove webhook subscriptions.
status_pages:read — Read public status page content and incident summaries.
status_pages:write — Publish maintenance windows and edit page branding.
billing:read — View plan details, usage metrics, and invoice history.
teams:read — List workspace members and their roles.
teams:write — Invite, remove, and reassign member roles.
Scope Composition Examples
Read-only monitoring dashboard: checks:read incidents:read status_pages:read
Automated check provisioning via Terraform: checks:write webhooks:write
PagerDuty or Opsgenie integration: incidents:write webhooks:write checks:read
Partner analytics app: checks:read incidents:read (never request billing:read or teams:write unless your product requires them).
Auditing Scope Usage
Every API request logs the scopes consumed in the Audit Log under Settings → Security. Filter by key label or OAuth application name to identify underused permissions. If a key holds checks:write but has only issued GET requests in the past 30 days, consider regenerating it with checks:read only. OAuth tokens return the granted scopes in the scp claim of the OIDC discovery endpoint at https://auth.statuspulse.io/.well-known/openid-configuration.
Need Help?
Contact the Platform Security Team
If you need custom scopes for a private integration, require extended token lifetimes for batch reporting, or have questions about key rotation automation, reach out to platform-security@statuspulse.io. Include your workspace ID (visible in the dashboard URL) and a brief description of your integration. Our team typically responds within one business day.