# povzscaler.com APIs

> Every povzscaler.com app has a JSON API, documented with OpenAPI. One povzscaler.com API token works
> for all of them. This file is the starting point for an agent: read it, then read the OpenAPI
> document of the app you need before calling it.

## Authentication

Send the token on every request:

    Authorization: Bearer povz_...

- Create tokens at https://account.povzscaler.com/tokens (signed in as the owner). Each token has
  scopes: `<app>:read` (GET only) or `<app>:write` (read and change), for apps `command`, `dns`,
  `console` and `account`. Tokens expire (90 days by default) and can be revoked there.
- On the owner's machines the token is kept in `~/.config/povzscaler/token` (mode 600). Read it
  from there; never print it, log it, or put it in a URL, a file in a repository, or a command
  shown to the user. Use: `-H "Authorization: Bearer $(cat ~/.config/povzscaler/token)"`.
- A missing or invalid token gets 401; a token without the needed scope gets 403 with a message
  naming the scope. Don't retry those: tell the user which scope the token needs.
- Errors are JSON: `{"detail": "..."}` in plain English.

## Environments

- Production: `https://<app>.povzscaler.com`
- Development: `https://<app>.dev.povzscaler.com`, separate data and separate tokens (made at
  https://account.dev.povzscaler.com/tokens). Try changes there first when unsure.

## The APIs

### Command Center: tasks, customers, PoVs (command.povzscaler.com)

- Base URL: https://command.povzscaler.com/api/v1
- OpenAPI: https://command.povzscaler.com/api/v1/openapi.json (docs: /api/v1/docs)
- Scopes: `command:read`, `command:write`
- No priorities: tasks carry facts (`when`, `waiting_on_me`, `waiting_on_them`, `blocks_others`,
  `due_date`) and the app works out the order. `GET /today` answers "what's on my plate".
- Areas, customers and PoVs can be named instead of using IDs.

Add a task:

    curl -sS https://command.povzscaler.com/api/v1/tasks \
      -H "Authorization: Bearer $(cat ~/.config/povzscaler/token)" \
      -H "Content-Type: application/json" \
      -d '{"title": "Send the ZIA readout to Acme", "area": "Epic Cyber — day to day", "when": "today", "customer": "Acme"}'

### DNS: GoDaddy DNS records (dns.povzscaler.com)

- Base URL: https://dns.povzscaler.com/api/v1
- OpenAPI: https://dns.povzscaler.com/api/v1/openapi.json (docs: /api/v1/docs)
- Scopes: `dns:read`, `dns:write`
- Changes the real, public DNS of the domains. A, AAAA, CNAME, MX and TXT can change; minimum TTL
  600. Records are addressed by type, name and current value (GoDaddy has no record IDs).
- Every change is in the audit log: `GET /audit`.

Point a new tool's subdomain at the Mac mini:

    curl -sS https://dns.povzscaler.com/api/v1/domains/povzscaler.com/records \
      -H "Authorization: Bearer $(cat ~/.config/povzscaler/token)" \
      -H "Content-Type: application/json" \
      -d '{"type": "A", "name": "notes", "data": "125.18.119.178", "ttl": 600}'

### Console: Zscaler clients, tenants, baselines, PoVs (console.povzscaler.com)

- Base URL: https://console.povzscaler.com/api
- OpenAPI: https://console.povzscaler.com/api/openapi.json (docs: /api/docs)
- Scopes: `console:read`, `console:write`; `/api/admin/*` also needs the `console:admin` role.
- Careful: calls that apply baselines or edit policy change a customer's live Zscaler tenant. Each
  says so in its description. Confirm with the user before calling one.

List clients:

    curl -sS https://console.povzscaler.com/api/clients \
      -H "Authorization: Bearer $(cat ~/.config/povzscaler/token)"

### Account: who you are, tokens, people and roles (account.povzscaler.com)

- Base URL: https://account.povzscaler.com/api/v1
- OpenAPI: https://account.povzscaler.com/api/openapi.json (docs: /api/docs)
- `GET /me` works with any token: use it to check a token. Managing tokens needs `account:write`;
  people and roles also need the `account:admin` role.

Check the token:

    curl -sS https://account.povzscaler.com/api/v1/me \
      -H "Authorization: Bearer $(cat ~/.config/povzscaler/token)"

## Rules for agents

- Read the app's OpenAPI document before the first call; field names and allowed values are there.
- Prefer the API over editing databases or files directly.
- Anything that changes public DNS or a customer's Zscaler tenant: confirm with the user first.