docs/reference/authentication.md

# Authentication

Mission Control supports two auth modes via `AUTH_MODE`:

- `local`: shared bearer token auth for self-hosted deployments
- `clerk`: Clerk JWT auth

## Local mode

Backend:

- `AUTH_MODE=local`
- `LOCAL_AUTH_TOKEN=<token>`

Frontend:

- `NEXT_PUBLIC_AUTH_MODE=local`
- Provide the token via the login UI.

## Clerk mode

Backend:

- `AUTH_MODE=clerk`
- `CLERK_SECRET_KEY=<secret>`

Frontend:

- `NEXT_PUBLIC_AUTH_MODE=clerk`
- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<key>`

## Agent authentication

Autonomous agents primarily authenticate via an `X-Agent-Token` header. On shared user/agent routes, the backend also accepts `Authorization: Bearer <agent-token>` after user auth does not resolve. See [API reference](api.md) for details.

Security notes:

- Agent auth is rate-limited to **20 requests per 60 seconds per IP**. Exceeding this returns `429 Too Many Requests`.
- Authentication failure logs never include token material.
docs: add initial docs/ information architecture + stubs 2026-02-11 21:43:05 +00:00			`# Authentication`

			Mission Control supports two auth modes via `AUTH_MODE`:

			- `local`: shared bearer token auth for self-hosted deployments
			- `clerk`: Clerk JWT auth

			`## Local mode`

			`Backend:`

			- `AUTH_MODE=local`
			- `LOCAL_AUTH_TOKEN=<token>`

			`Frontend:`

			- `NEXT_PUBLIC_AUTH_MODE=local`
			`- Provide the token via the login UI.`

			`## Clerk mode`

			`Backend:`

			- `AUTH_MODE=clerk`
			- `CLERK_SECRET_KEY=<secret>`

			`Frontend:`

			- `NEXT_PUBLIC_AUTH_MODE=clerk`
			- `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<key>`
docs: document security hardening changes from security review Add documentation for all user/operator-facing changes introduced by the security review branch: rate limits, security headers, webhook HMAC verification, payload size limits, gateway token redaction, non-root containers, agent token logging, and prompt injection mitigation. Updated: docs/reference/api.md, docs/reference/authentication.md, docs/reference/configuration.md, docs/deployment/README.md, docs/operations/README.md, docs/openclaw_gateway_ws.md, backend/README.md. Created: docs/reference/security.md (consolidated security reference). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-03-03 14:51:52 -07:00
			`## Agent authentication`

fix(security): Close review follow-up gaps Rate-limit the optional agent bearer path after user auth resolution so mixed user/agent routes no longer leave an unthrottled PBKDF2 path. Stop logging token prefixes on agent auth failures and require a locally supplied token for backend/.env.test instead of committing one. Update tests and docs to cover agent bearer fallback, configurable webhook signature headers, and the operator-facing security settings added by the hardening work. Co-Authored-By: Claude <noreply@anthropic.com> 2026-03-07 23:40:50 +05:30			Autonomous agents primarily authenticate via an `X-Agent-Token` header. On shared user/agent routes, the backend also accepts `Authorization: Bearer <agent-token>` after user auth does not resolve. See [API reference](api.md) for details.
docs: document security hardening changes from security review Add documentation for all user/operator-facing changes introduced by the security review branch: rate limits, security headers, webhook HMAC verification, payload size limits, gateway token redaction, non-root containers, agent token logging, and prompt injection mitigation. Updated: docs/reference/api.md, docs/reference/authentication.md, docs/reference/configuration.md, docs/deployment/README.md, docs/operations/README.md, docs/openclaw_gateway_ws.md, backend/README.md. Created: docs/reference/security.md (consolidated security reference). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> 2026-03-03 14:51:52 -07:00
			`Security notes:`

			- Agent auth is rate-limited to 20 requests per 60 seconds per IP. Exceeding this returns `429 Too Many Requests`.
fix(security): Close review follow-up gaps Rate-limit the optional agent bearer path after user auth resolution so mixed user/agent routes no longer leave an unthrottled PBKDF2 path. Stop logging token prefixes on agent auth failures and require a locally supplied token for backend/.env.test instead of committing one. Update tests and docs to cover agent bearer fallback, configurable webhook signature headers, and the operator-facing security settings added by the hardening work. Co-Authored-By: Claude <noreply@anthropic.com> 2026-03-07 23:40:50 +05:30			`- Authentication failure logs never include token material.`