Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: add agent identity guide (token, agent-id, sessions)

Bosch21a87dc7e531
diff --git a/docs/guides/agent-identity.md b/docs/guides/agent-identity.md
new file mode 100644
index 00000000..1546abf0
--- /dev/null
+++ b/docs/guides/agent-identity.md
@@ -0,0 +1,154 @@
+# Agent Identity
+
+PinchTab offers three levels of agent identification, from simple to fully managed. Pick the one that fits your setup.
+
+## Server Token
+
+Every PinchTab server has a bearer token configured in `server.token`. This is the baseline authentication method — it proves the caller is authorized to use the server, but says nothing about *which* agent is making the request.
+
+```bash
+pinchtab --token "your-server-token" nav https://example.com
+```
+
+Or via environment variable:
+
+```bash
+export PINCHTAB_TOKEN=your-server-token
+pinchtab nav https://example.com
+```
+
+**When to use:** Single-agent setups, quick scripting, or when you don't need per-agent tracking.
+
+**Limitation:** All requests look the same in the activity feed — no way to tell which agent did what.
+
+## Agent ID
+
+Adding an agent ID tags every request with a name. This shows up in the activity feed and the dashboard's Agents page. The server still authenticates via the bearer token, but now each request carries an identity.
+
+```bash
+pinchtab --agent-id bosch nav https://example.com
+```
+
+Or via environment variable:
+
+```bash
+export PINCHTAB_AGENT_ID=bosch
+pinchtab nav https://example.com
+```
+
+The `X-Agent-Id` header is sent with every request. No server-side setup required — any string works.
+
+**When to use:** Multiple agents sharing one server where you want to see who did what, but don't need session management.
+
+**Limitation:** No revocation, no idle tracking, no labels. The agent ID is self-declared — any caller can claim any identity.
+
+## Agent Sessions
+
+Sessions are the full identity solution. Each session is a revocable, server-managed token tied to a specific agent ID. Sessions provide:
+
+- **Labels** — human-readable names like "research task" or "daily scrape"
+- **Activity grouping** — all requests within a session are grouped in the dashboard
+- **Idle timeout** — sessions expire after 12 hours of inactivity (configurable)
+- **Max lifetime** — hard expiry after 24 hours (configurable)
+- **Revocation** — kill a session without rotating the server token
+- **Rotation** — generate a new token for an existing session
+
+### Enable Sessions
+
+Add to your `config.json`:
+
+```json
+{
+ "sessions": {
+ "agent": {
+ "enabled": true,
+ "mode": "preferred"
+ }
+ }
+}
+```
+
+Modes:
+
+| Mode | Behavior |
+|------|----------|
+| `off` | Agent sessions disabled |
+| `preferred` | Both bearer and session auth accepted (default when enabled) |
+| `required` | Only session auth accepted for agents |
+
+### Create a Session
+
+```bash
+curl -X POST http://localhost:9867/api/agent-sessions \
+ -H "Authorization: Bearer $PINCHTAB_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"agentId": "bosch", "label": "research task"}'
+```
+
+Response:
+
+```json
+{
+ "id": "pts_e6ac8132fe7e7016",
+ "agentId": "bosch",
+ "label": "research task",
+ "sessionToken": "pts_1138f72e77f23c49...",
+ "status": "active"
+}
+```
+
+The `sessionToken` is returned exactly once. Store it — PinchTab only persists the hash.
+
+### Use a Session
+
+```bash
+export PINCHTAB_SESSION=pts_1138f72e77f23c49...
+pinchtab nav https://example.com
+pinchtab snap -i -c
+pinchtab click e5
+```
+
+Or pass the header directly:
+
+```bash
+curl -X POST http://localhost:9867/navigate \
+ -H "Authorization: Session pts_1138f72e77f23c49..." \
+ -H "Content-Type: application/json" \
+ -d '{"url": "https://example.com"}'
+```
+
+No need to set `--agent-id` — the session carries the agent identity.
+
+### Manage Sessions
+
+```bash
+# List all sessions
+curl http://localhost:9867/api/agent-sessions \
+ -H "Authorization: Bearer $PINCHTAB_TOKEN"
+
+# Rotate token (old token invalidated, new one returned)
+curl -X POST http://localhost:9867/api/agent-sessions/pts_e6ac8132fe7e7016/rotate \
+ -H "Authorization: Bearer $PINCHTAB_TOKEN"
+
+# Revoke
+curl -X POST http://localhost:9867/api/agent-sessions/pts_e6ac8132fe7e7016/revoke \
+ -H "Authorization: Bearer $PINCHTAB_TOKEN"
+```
+
+### Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `sessions.agent.enabled` | `false` | Enable agent sessions |
+| `sessions.agent.mode` | `preferred` | Auth mode: `off`, `preferred`, `required` |
+| `sessions.agent.idleTimeoutSec` | `43200` (12h) | Session expires after this many seconds of inactivity |
+| `sessions.agent.maxLifetimeSec` | `86400` (24h) | Hard session expiry |
+
+## Choosing the Right Level
+
+| Scenario | Recommendation |
+|----------|----------------|
+| One agent, local only | Server token is enough |
+| Multiple agents, want attribution | Add `--agent-id` or `PINCHTAB_AGENT_ID` |
+| Production multi-agent, need revocation | Use agent sessions |
+| Shared server, untrusted agents | Use sessions with `mode: "required"` |