API Keys & Scopes
API Keys are the primary method of interacting programmatically with Pinger. Each API key belongs to a specific Workspace and can be restricted to specific permissions called scopes.
Creating an API Key
To create a new API key:
- Log in to your Pinger Dashboard.
- Navigate to the Settings > API Keys tab.
- Click Generate Key.
- Assign a descriptive name and select the necessary scopes.
- Store the generated
pinger_...token securely. It will not be shown again.
Supported Scopes
Scopes define what an API key is allowed to do. When creating a key, you must grant it one or more scopes. Pinger currently supports the following scopes:
| Scope | Type | Description |
|---|---|---|
monitors:read | Read | Allows the key to query monitors, ping logs, real-time uptime status, and latency metrics. |
monitors:write | Write | Allows the key to create, update, pause/resume, and delete monitors in the workspace. |
incidents:read | Read | Allows reading published incident histories, timeline entries, and scheduled maintenance windows. |
incidents:write | Write | Allows creating and publishing incident alerts, posting progress updates, and scheduling maintenance outages. |
heartbeats:write | Write | Allows sending cron job check-ins and pushing worker heartbeats or telemetry logs. |
status:read | Read | Allows reading public status page configuration and custom domain verification status. |
Note: The monitors:write scope inherently allows reading monitor data to facilitate update workflows.
Revocation and Rotation
If you suspect an API key has been compromised, you should revoke it immediately from the Dashboard. Once revoked, any API request utilizing that key will immediately fail with a 401 Unauthorized status.
We recommend rotating your API keys periodically. To rotate a key without downtime:
- Generate a new API key with the exact same scopes.
- Update your application's environment variables to use the new key.
- Deploy your application.
- Revoke the old API key in the Pinger Dashboard.
Plan Restrictions
The number of active API keys you can have per workspace is governed by your subscription plan. For example, the Free plan allows 1 API key, while Business plans support unlimited keys. Check your Billing page to view your limits.