API Keys

Create, scope, copy, rotate, and revoke PulsAPI API keys for programmatic access to status, incident, and SLA data.

API keys let you interact with the PulsAPI API programmatically, pull service statuses, retrieve SLA data, or integrate PulsAPI into your own tooling.

Public status reads need no key at all. GET /api/services, GET /api/services/{slug}, GET /api/incidents, and the provider overview are open to anyone. A key is for account data: SLA reports, monitors, alert rules, and the full MCP tool set. The complete surface is in the OpenAPI specification, and the developer hub has the shortest working example of each.

API keys are a Pro plan feature. Upgrade to Pro to create and manage API keys.

Creating an API key

Navigate to Settings > API Keys.
Click Create API Key.
Enter a name for the key (e.g., "CI/CD Pipeline", "Internal Dashboard").
Choose the scopes the key needs. Leaving them unselected grants every scope; pick the narrowest set that does the job.
Click Create.
Your new API key is displayed. Copy it now, it will not be shown again.

The full API key is only displayed once at the time of creation. If you lose it, you must revoke the key and create a new one. There is no way to retrieve an existing key.

Copying the key

After creating a key, click the Copy button next to the key value to copy it to your clipboard. Store it securely, for example, in a password manager or as an encrypted environment variable.

Using API keys

Send your key either as an X-API-Key header or as a bearer token. Both are accepted:

curl -H "X-API-Key: YOUR_API_KEY" \
  https://www.pulsapi.com/api/user/api-keys
 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.pulsapi.com/api/user/services/stripe/sla

The base URL is https://www.pulsapi.com/api. The key authenticates requests as your account, and every action stays subject to your account's plan, your role, and the key's own scopes.

Scopes

Each key carries an explicit list of what it may do. An endpoint refuses a key that lacks its scope with 403 and names the scope it wanted, so a script that hits one tells you exactly which key to replace:

{
  "error": "insufficient_scope",
  "status": 403,
  "requiredScope": "sla:read",
  "message": "This API key was not granted the 'sla:read' scope."
}

Scope	Grants
`status:read`	Public service, provider, and component status, uptime, and status history.
`incidents:read`	Incident timelines for the catalog and for individual services.
`sla:read`	SLA reports, uptime percentages, MTTR, latency percentiles, and breach history.
`monitors:read`	The monitors, boards, and groups configured on the account.
`monitors:write`	Create, update, and delete monitors, boards, groups, and subscriptions.
`alerts:read`	Alert rules, routes, escalation policies, and delivered alert events.
`alerts:write`	Create, update, and delete alert rules, routes, and escalation policies.
`account:read`	Account profile, plan, seats, and API-key metadata.
`mcp:invoke`	Call the MCP server at `/api/mcp` as an AI agent tool surface.

GET /api/user/api-keys/scopes returns the same list, so a script or an agent can read it rather than hard-coding it.

Keys created before scopes existed hold every scope, so nothing that already worked stopped working. Narrow them the next time you rotate.

Revoking an API key

If a key is compromised or no longer needed, revoke it immediately:

Navigate to Settings > API Keys.
Find the key you want to revoke in the list.
Click the Revoke button.
Confirm the revocation.

The key becomes invalid immediately. Any requests using the revoked key will receive a 401 Unauthorized response.

Security best practices

Follow these guidelines to keep your API keys secure:

Never commit API keys to version control. Use environment variables or a secrets manager instead.
Use descriptive names for each key so you can identify its purpose and revoke the right one if needed.
Rotate keys periodically. Create a new key, update your integrations, then revoke the old one.
Revoke unused keys. If a key is no longer in use, revoke it to minimize your attack surface.
Limit access. Only share API keys with systems and people who need them.
Scope narrowly. A key handed to an agent or a CI job usually needs status:read and nothing else. A key that can only read status cannot delete an alert rule, however it leaks.

Managing multiple keys

You can create multiple API keys, for example, one for your CI/CD system and another for a custom internal dashboard. Each key is listed in Settings > API Keys with its name, creation date, and a revoke action.

Column	Description
Name	The label you assigned when creating the key.
Scopes	What this key is permitted to do.
Created	The date and time the key was generated.
Last Used	The last time the key was used to make an API request.
Actions	Revoke the key.