From cee24ff7e0a6986f61f2a18ecaac4e0a19c451da Mon Sep 17 00:00:00 2001 From: rcourtman Date: Thu, 23 Oct 2025 13:44:19 +0000 Subject: [PATCH] docs: refresh API token scope guidance --- docs/API.md | 17 ++++++++++++----- docs/DOCKER_MONITORING.md | 5 +++-- docs/HOST_AGENT.md | 2 +- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/API.md b/docs/API.md index 69f4912e3..480b4e681 100644 --- a/docs/API.md +++ b/docs/API.md @@ -319,7 +319,7 @@ GET /install-docker-agent.sh # Download the installation convenience sc GET /download/pulse-docker-agent # Download the standalone Docker agent binary ``` -Agent routes require authentication. Use an API token or an authenticated session when calling them from automation. The payload reports restart loops, exit codes, memory pressure, and health probes per container, and Pulse de-duplicates heartbeats per agent ID so you can fan out to multiple Pulse instances safely. Host responses mirror the `/api/state` data, including `issues`, `recentExitCodes`, and `lastSeen` timestamps so external tooling can mimic the built-in Docker workspace. +Agent routes require authentication. Use an API token or an authenticated session when calling them from automation. When authenticating with tokens, grant `docker:report` for `POST /api/agents/docker/report`, `docker:manage` for Docker host lifecycle endpoints, and `host-agent:report` for host agent submissions. The payload reports restart loops, exit codes, memory pressure, and health probes per container, and Pulse de-duplicates heartbeats per agent ID so you can fan out to multiple Pulse instances safely. Host responses mirror the `/api/state` data, including `issues`, `recentExitCodes`, and `lastSeen` timestamps so external tooling can mimic the built-in Docker workspace. ## Monitoring Data @@ -491,7 +491,9 @@ Request body: #### API Token Management Manage API tokens for automation workflows, Docker agents, and tool integrations. -Authentication: Requires an admin session or an existing admin-scoped API token. +Authentication: Requires an admin session or an API token with the scope(s) below: +- `settings:read` for `GET /api/security/tokens` +- `settings:write` for `POST /api/security/tokens` and `DELETE /api/security/tokens/{id}` **List tokens** ```bash @@ -508,7 +510,8 @@ Response: "prefix": "pulse_1a2b", "suffix": "c3d4", "createdAt": "2025-10-14T12:12:34Z", - "lastUsedAt": "2025-10-14T12:21:05Z" + "lastUsedAt": "2025-10-14T12:21:05Z", + "scopes": ["docker:report", "monitoring:read"] } ] } @@ -519,10 +522,13 @@ Response: POST /api/security/tokens Content-Type: application/json { - "name": "ansible" + "name": "ansible", + "scopes": ["monitoring:read"] } ``` +> Omit the `scopes` field to mint a full-access token (`["*"]`). When present, the array must include one or more known scopes—see `docs/CONFIGURATION.md` for the canonical list and descriptions. + Response (token value is returned once): ```json { @@ -533,7 +539,8 @@ Response (token value is returned once): "prefix": "pulse_1a2b", "suffix": "c3d4", "createdAt": "2025-10-14T12:12:34Z", - "lastUsedAt": null + "lastUsedAt": null, + "scopes": ["monitoring:read"] } } ``` diff --git a/docs/DOCKER_MONITORING.md b/docs/DOCKER_MONITORING.md index 659658f91..d9cf2640a 100644 --- a/docs/DOCKER_MONITORING.md +++ b/docs/DOCKER_MONITORING.md @@ -18,6 +18,7 @@ Data is pushed to Pulse over HTTPS using your existing API token – no inbound ## Prerequisites - Pulse v4.22.0 or newer with an API token enabled (`Settings → Security`) +- API token with the `docker:report` scope (add `docker:manage` if you use remote lifecycle commands) - Docker 20.10+ on Linux (the agent uses the Docker Engine API via the local socket) - Access to the Docker socket (`/var/run/docker.sock`) or a configured `DOCKER_HOST` - Go 1.24+ if you plan to build the binary from source @@ -38,7 +39,7 @@ Copy the binary to your Docker host (e.g. `/usr/local/bin/pulse-docker-agent`) a ### Quick install from your Pulse server -Use the bundled installation script (ships with Pulse v4.22.0+) to deploy and manage the agent. Replace the token placeholder with an API token generated in **Settings → Security**. Create a dedicated token for each Docker host so you can revoke individual credentials without touching others—sharing one token across many hosts makes incident response much harder. +Use the bundled installation script (ships with Pulse v4.22.0+) to deploy and manage the agent. Replace the token placeholder with an API token generated in **Settings → Security**. Create a dedicated token for each Docker host so you can revoke individual credentials without touching others—sharing one token across many hosts makes incident response much harder. Tokens used here should include the `docker:report` scope so the agent can submit telemetry (add `docker:manage` only if you plan to issue lifecycle commands remotely). ```bash curl -fsSL http://pulse.example.com/install-docker-agent.sh \ @@ -130,7 +131,7 @@ docker run -d \ | Flag / Env var | Description | Default | | ----------------------- | --------------------------------------------------------- | --------------- | | `--url`, `PULSE_URL` | Pulse base URL (http/https). | `http://localhost:7655` | -| `--token`, `PULSE_TOKEN`| Pulse API token (required). | — | +| `--token`, `PULSE_TOKEN`| Pulse API token with `docker:report` scope (required). | — | | `--target`, `PULSE_TARGETS` | One or more `url|token[|insecure]` entries to fan-out reports to multiple Pulse servers. Separate entries with `;` or repeat the flag. | — | | `--interval`, `PULSE_INTERVAL` | Reporting cadence (supports `30s`, `1m`, etc.). | `30s` | | `--hostname`, `PULSE_HOSTNAME` | Override host name reported to Pulse. | Docker info / OS hostname | diff --git a/docs/HOST_AGENT.md b/docs/HOST_AGENT.md index 74aa36790..18cdb9411 100644 --- a/docs/HOST_AGENT.md +++ b/docs/HOST_AGENT.md @@ -81,7 +81,7 @@ A Windows build will ship shortly. In the meantime run the Linux/WSL binary or c | Flag | Description | |------|-------------| | `--url` | Pulse base URL (defaults to `http://localhost:7655`) | -| `--token` | API token with monitoring write access | +| `--token` | API token with the `host-agent:report` scope | | `--interval` | Polling interval (`30s` default) | | `--hostname` | Override reported hostname | | `--agent-id` | Override agent identifier (used as dedupe key) |