> ## Documentation Index
> Fetch the complete documentation index at: https://pulse-41cf5b0d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  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.
</Note>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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             |
  </Step>

  <Step title="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.

    <Warning>
      You cannot retrieve the raw key value after you close this dialog. If you lose it, revoke the key and create a new one.
    </Warning>
  </Step>
</Steps>

## Using Your Key in API Requests

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

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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`:

```bash theme={null}
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:

```bash theme={null}
pulse auth status
```

To remove the stored credentials, run:

```bash theme={null}
pulse auth logout
```

<Tip>
  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.
</Tip>

## 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:

```json theme={null}
{
  "error": "Invalid or missing API key"
}
```

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

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>