Authenticate REST API Requests to PulseGuard

Every request to the PulseGuard API must include a valid API key. Keys are long-lived tokens you create in the dashboard and carry both read and write scopes by default. You may set an optional expiry date. PulseGuard hashes each key with SHA-256 and stores only the hash — the raw key is shown exactly once and cannot be retrieved again, so copy it to a safe location immediately after creation.

API key format

PulseGuard API keys follow this structure:

pg_live_<48 hex characters>

Example: pg_live_a3f8c2d1e4b5a6f7c8d9e0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 The pg_live_ prefix makes it easy to identify PulseGuard keys in your environment variables and secret managers.

Key scopes

Every API key carries both read and write scopes. The scopes are stored as a comma-separated string (read,write) and the write scope is enforced on all endpoints that create, modify, or delete resources:

read

Included in every key. GET endpoints require a valid key but do not explicitly check for this scope — any unexpired key grants read access.

write

Required for POST, PUT, and DELETE requests. Creating or modifying monitors, triggering checks with a URL override, and deleting resources all explicitly check for this scope and return 403 if it is absent.

All newly created keys include both scopes. If a key is compromised, delete it immediately from the dashboard — it will stop accepting requests instantly.

Create an API key

Open API Keys settings

In the PulseGuard dashboard, navigate to Settings → API Keys.

Click New Key

Click New Key and enter a descriptive name (e.g. ci-pipeline, grafana-monitoring).

Set an optional expiry

If you want the key to expire automatically, set an expiry date. Leave it blank for a non-expiring key.

Copy the raw key

After creation, the full raw key is displayed once. Copy it to your password manager or secret store immediately — PulseGuard stores only the SHA-256 hash and cannot show the raw key again.

Send authenticated requests

Add the key to the Authorization header of every request using the Bearer scheme. curl:

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

JavaScript (fetch):

const response = await fetch('https://app.pulseguard.io/api/cli/monitors', {
  headers: {
    'Authorization': `Bearer ${process.env.PULSEGUARD_API_KEY}`,
    'Content-Type': 'application/json'
  }
});
const { monitors } = await response.json();

Environment variable convention: Store your key in an environment variable named PULSEGUARD_API_KEY to keep it out of source code.

export PULSEGUARD_API_KEY="pg_live_your_api_key_here"

How PulseGuard verifies your key

When your request arrives, PulseGuard:

Reads the Authorization: Bearer <key> header.
Hashes the raw key with SHA-256.
Looks up the hash in the database.
Checks whether the key has expired (expiresAt < now).
Returns the associated userId and scopes string (comma-separated, e.g. read,write).

If any step fails, the request is rejected with a 401. PulseGuard also asynchronously records a lastUsedAt timestamp so you can audit usage in the dashboard without adding latency to your request.

401 vs 403 errors

Status	Cause	Resolution
`401 Unauthorized`	The key is missing, not recognized, or has expired	Check the `Authorization` header format; verify the key has not expired in the dashboard
`403 Forbidden`	The key is valid but lacks the `write` scope	All current keys include `write` scope; this error can occur if a key was created with a custom scope configuration

Rotate a key

Create the replacement key

In Settings → API Keys, create a new key with the same scope as the one you are replacing. Copy the raw key.

Update your integrations

Replace the old value of PULSEGUARD_API_KEY (or wherever you store the key) in every service, CI pipeline, and secret manager.

Delete the old key

Once all integrations are updated and confirmed working, delete the old key from the dashboard. It will immediately stop accepting requests.

Deleting a key is irreversible and takes effect immediately. Any service still using the old key will receive 401 errors after deletion.

​API key format

​Key scopes

read

write

​Create an API key

​Send authenticated requests

​How PulseGuard verifies your key

​401 vs 403 errors

​Rotate a key

API key format

Key scopes

Create an API key

Send authenticated requests

How PulseGuard verifies your key

401 vs 403 errors

Rotate a key