PulseGuard Authentication: API Keys and CLI Access

PulseGuard secures all programmatic access — including the pulse CLI and every REST API endpoint — with scoped API keys. Each key carries a set of permission scopes, an optional expiry date, and is stored only as a SHA-256 hash on PulseGuard’s servers. The raw key value is shown to you exactly once when you create it. If you lose it, you generate a new one.

API Key Format

Every PulseGuard API key follows this structure:

pg_live_<48 hex characters>

For example: pg_live_3c8a9f2b1d7e4605c92a3b8f1d6e7a4b9c2e5f08d7a3b6c1. The pg_live_ prefix makes keys easy to identify in logs and secret scanners. Keys are 56 characters in total and carry approximately 192 bits of entropy.

Never expose your API key in client-side code, public repositories, or anywhere that isn’t a secrets manager or a secured environment variable. If a key is accidentally exposed, revoke it immediately from the dashboard.

Scopes

When you create a key, PulseGuard assigns it a comma-separated list of scopes. The available scopes are:

Scope	Permissions
`read`	List monitors, view check results, inspect incidents and status pages
`write`	Create and update monitors, manage alert channels, modify status pages

A key with both read and write scopes is the default. You can issue read-only keys for observability integrations that should never be able to modify configuration.

Creating an API Key

Open API Keys settings

In the PulseGuard dashboard, navigate to Settings → API Keys. You’ll see a list of all existing keys with their name, prefix, scopes, last-used timestamp, and optional expiry date.

Click New API Key

Click New API Key and fill in the form:

Field	Description
Name	A human-readable label (e.g., `ci-pipeline`, `terraform`)
Scopes	Select `read`, `write`, or both
Expiry	Optional — leave blank for a non-expiring key

Copy your key

After you click Create, PulseGuard displays the full raw key exactly once. Copy it to a secure location — a password manager or a secrets manager like AWS Secrets Manager, Doppler, or 1Password.

You cannot retrieve the raw key value after you close this dialog. If you lose it, revoke the key and create a new one.

Using Your Key in API Requests

Pass your API key in the Authorization HTTP header using the Bearer scheme:

curl https://app.pulseguard.io/api/cli/monitors \
  -H "Authorization: Bearer pg_your_api_key_here"

To create a monitor, add -X POST, set Content-Type, and include a JSON body:

curl https://app.pulseguard.io/api/cli/monitors \
  -X POST \
  -H "Authorization: Bearer pg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "url": "https://api.yourapp.com/health",
    "type": "HTTP",
    "interval": 60,
    "method": "GET"
  }'

A successful response returns 201 Created with the new monitor object:

{
  "monitor": {
    "id": "mon_01j...",
    "name": "Production API",
    "url": "https://api.yourapp.com/health",
    "type": "HTTP",
    "status": "PENDING",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Using Your Key in the CLI

Authenticate the pulse CLI by passing your key to pulse auth login:

pulse auth login --key pg_live_a3f1b2c9d4e5f6...

The CLI stores the key locally in its configuration file and reuses it for all subsequent commands. To confirm the CLI is authenticated, run:

pulse auth status

To remove the stored credentials, run:

pulse auth logout

For CI/CD environments, set the PULSE_API_KEY environment variable instead of relying on the persisted config file. Most pulse commands read this variable automatically when no stored key is found.

Error Responses

The API returns standard HTTP status codes for authentication failures:

Status	Code	Meaning
`401 Unauthorized`	`invalid_api_key`	The `Authorization` header is missing, malformed, or the key does not exist
`401 Unauthorized`	`expired_api_key`	The key existed but has passed its expiry date
`403 Forbidden`	`insufficient_scope`	The key exists and is valid, but lacks the required scope (e.g., a `read`-only key tried a `write` operation)

A 401 response body looks like this:

{
  "error": "Invalid or missing API key"
}

A 403 response for a missing write scope looks like this:

{
  "error": "Write scope required"
}

Revoking a Key

To revoke a key, go to Settings → API Keys, find the key by its name or prefix, and click Revoke. Revocation is immediate — any in-flight requests using that key will begin receiving 401 responses.

Revoking a key is permanent. Any CLI installations, scripts, or integrations that use the revoked key will stop working immediately. Make sure you rotate the key in all consuming systems before or immediately after revoking.

Get Started

Monitors

Alerting

Status Pages

Private Probes

Tools

PulseGuard Authentication: API Keys and CLI Access

API Key Format

Scopes

Creating an API Key

Using Your Key in API Requests

Using Your Key in the CLI

Error Responses

Revoking a Key

​API Key Format

​Scopes

​Creating an API Key

​Using Your Key in API Requests

​Using Your Key in the CLI

​Error Responses

​Revoking a Key

API Key Format

Scopes

Creating an API Key

Using Your Key in API Requests

Using Your Key in the CLI

Error Responses

Revoking a Key