# Cloudflare API Integration

## Setup instructions for the user

When the user generates a Cloudflare API token:

1. Go to **dash.cloudflare.com → My Profile → API Tokens**
2. Use **"Edit zone DNS"** template (not blank)
3. Change Zone Resources from "Specific zone" to **"All zones"**
4. Leave TTL as **"Never expire"** (token can be revoked manually)
5. Permissions needed:
   - Zone → DNS → **Edit** (read + write DNS records)
   - Account → Account Settings → **Read** (list zones)
6. Set Client IP Filtering to **none** (or specific office IPs for extra security)

## Verification

```bash
# Verify token is active
curl -s -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer $TOKEN"

# List all zones
curl -s -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer $TOKEN"

# List DNS records for a zone
curl -s "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records?per_page=5" \
  -H "Authorization: Bearer $TOKEN"
```

## Storage

Save to `~/.hermes/.env` as `CLOUDFLARE_API_TOKEN=<token>`. The token has an ID that can be looked up later for revocation:

```bash
grep CLOUDFLARE_API_TOKEN ~/.hermes/.env | cut -d= -f2-
```

## Endpoints used

- `GET /client/v4/zones` — list all zones
- `GET /client/v4/zones/:id/dns_records` — list records
- `POST /client/v4/zones/:id/dns_records` — create record
- `PATCH /client/v4/zones/:id/dns_records/:id` — update record
- `DELETE /client/v4/zones/:id/dns_records/:id` — delete record

## Portal mockup

The DNS management page is at `/root/portal-mockup/dns.html` (Tailscale-served).