PulseGuard Authentication: API Keys and CLI Access

PulseGuard uses scoped API keys for the CLI and REST API. Learn how to create, use, and revoke keys, and how to handle auth errors.

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

1. 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.

2. 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

3. 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.