> ## Documentation Index
> Fetch the complete documentation index at: https://docs.happyuptime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

API keys, scopes, and where the CLI stores credentials.

# CLI authentication

## Three sources, in priority order

1. `--api-key` flag on the command line (highest priority)
2. `HAPPYUPTIME_API_KEY` environment variable
3. `~/.happyuptime/config.json` (created by `happy login`)

## happy login (recommended)

```bash
happy login
```

Walks through the OAuth device flow:
1. Prints a URL + 8-character code.
2. Opens your browser.
3. You confirm in the dashboard.
4. The CLI stores your API key locally.

```bash
happy whoami
# Logged in as you@example.com (org: Acme)

happy logout
# Removes ~/.happyuptime/config.json
```

## Manual API key

Dashboard → **Settings → API Keys** → **Create Key**. Pick a scope (`read`, `write`, `admin`). Copy the `hu_…` token (shown once).

Use it via env var or flag:

```bash
export HAPPYUPTIME_API_KEY=hu_xxxxx_yyyyy
happy monitors list
```

## Scopes

| Scope | Permissions |
|---|---|
| `read` | GET endpoints only |
| `write` | GET + POST + PUT + DELETE on monitors, incidents, status pages, alerts, on-call |
| `admin` | Everything including settings, team, billing |

Most CI use cases want `write`. Tools that just check status from a script can use `read`.

## Rotating

Create a new key, update your CI secrets, then revoke the old one. Revoke is instant.

## Storage details

`~/.happyuptime/config.json`:

```json
{
  "api_key": "hu_xxxxx",
  "endpoint": "https://happyuptime.com/api/v1",
  "user_email": "you@example.com",
  "logged_in_at": "2026-04-18T15:23:11Z"
}
```

File is created with mode 0600 (read/write owner only).