API Authentication: Working with Access Keys
Monitoring availability with second-level precision — secure your integrations with properly scoped API keys
Creating API Keys in the Dashboard
Every Pulsely account comes with API access. Generate keys directly from your dashboard to connect external tools, CI/CD pipelines, or custom dashboards to your monitoring infrastructure.
Navigate to Settings → API Keys in your Pulsely dashboard. Click Generate New Key, assign it a descriptive name such as ci-pipeline-production or grafana-dashboard, and select the appropriate permission scope before confirming. Your new key will appear immediately in the format ply_live_4f8a2c…9e1d. Copy it now — you won't be able to view the full value again.
1. Navigate to API Settings
Open your Pulsely dashboard, click your workspace name in the top bar, then select Settings → API Keys from the sidebar menu. Only workspace admins and API-managers can access this page.
2. Name & Scope Your Key
Give each key a unique identifier. Assign the narrowest scope needed — read:checks for dashboards, write:alerts for alerting bridges. Avoid the admin:* wildcard unless absolutely necessary.
3. Store & Rotate
Copy the key into your environment variables or secret manager immediately. Set a rotation schedule — Pulsely recommends regenerating keys every 90 days. Expired keys can be revoked instantly from the dashboard.
Security Rules for API Key Management
A leaked API key can expose your monitoring data or allow unauthorized changes to your check configurations. Follow these rules to keep your Pulsely integrations secure.
Never Hardcode Keys
Store keys in environment variables or a secret manager like HashiCorp Vault, AWS Secrets Manager, or Doppler. Reference them via PULSELY_API_KEY in your application config. Committing keys to Git — even in private repos — is the #1 cause of credential leaks.
Use Separate Keys per Environment
Maintain distinct keys for production, staging, and development workspaces. Name them accordingly (ply_live_prod_…, ply_test_stg_…) and restrict each key's scope to only the resources it needs to access.
Monitor Key Activity
Pulsely logs every API request with timestamp, IP address, and endpoint. Review the API Audit Log under Settings weekly. If you see unexpected activity from an unfamiliar IP like 91.234.56.78, revoke the key immediately and generate a replacement.
Enforce 90-Day Rotation
Set a calendar reminder or automate rotation via your infrastructure-as-code pipeline. Pulsely supports dual-key overlap during rotation — create the new key before revoking the old one to avoid downtime in your monitoring stack.
Scope Limitations & Permission Matrix
Pulsely uses fine-grained scopes to control what each API key can access. Select scopes at key creation time — they cannot be modified afterward. If you need broader permissions, generate a new key.
Each scope grants access to specific API resource groups. The table below outlines all available scopes and their capabilities:
read:checks
List all uptime checks, retrieve check configurations, and view historical status data. Suitable for read-only dashboards and reporting tools. Does not allow modifying or deleting checks.
write:checks
Create, update, pause, and delete uptime checks. Grants full lifecycle management of check definitions. Required for CI/CD pipelines that provision monitoring checks alongside deployments.
read:alerts
View alert rules, notification channel configurations, and alert history. Useful for audit tools and compliance reporting. Does not permit creating or modifying alert rules.
write:alerts
Create and update alert rules, manage notification channels (Slack, PagerDuty, email), and acknowledge incidents. Required for automated alerting bridges and incident management integrations.
read:metrics
Access response time metrics, uptime percentages, and geographic latency data via the metrics API. Powers custom Grafana dashboards and performance trend analysis. Rate-limited to 60 requests per minute.
admin:*
Full administrative access including workspace management, team member invitations, billing information, and API key management. Use only for service accounts that require unrestricted access. Strongly discouraged for personal or shared keys.
A single key can hold multiple scopes. For example, a Grafana integration might need read:checks + read:metrics, while your CI/CD pipeline might require write:checks + write:alerts. When in doubt, start with the most restrictive scope and expand only if your integration fails with a 403 Forbidden response.