Authentication — Agent token

Every request to the Agent API needs one thing:

Authorization: Bearer <agent-token>

The agent token is a 64-character hex string with no prefix. Whet Desktop generates it on first launch and persists it in your OS keychain. It's the same token the CLI saves to ~/.whet/config.json and the MCP clients carry in their Authorization header.

No HMAC signing secret, no pk_live_* / pk_test_* keys, no per-request signatures. Just the Bearer token. Inbound webhook receivers (Basic / Pro cloud feature) use a separate HMAC scheme — see Webhooks · HMAC verification.

Token lifecycle

Phase	What happens
Generation	Whet Desktop generates a 64-char hex token on first launch and writes it into your OS keychain (macOS Keychain, Windows DPAPI, Linux libsecret).
Distribution	The CLI's whet auth login reads it for the local instance (or accepts an explicit --token for a remote Team / Enterprise host) and stores it under ~/.whet/config.json (permissions 600). MCP clients carry it in their config JSON.
Rotation	Open Settings → Agent tokens in the workbench and click Rotate. The old token is revoked immediately; the new one shows once for you to copy and propagate to your CLI / MCP configs.
Revocation	Same UI: Revoke invalidates the token without minting a replacement. Useful when a token is suspected leaked.

Scopes

Today the agent token has full workspace scope. There are no per-scope tokens (org:read, artifacts:publish, etc.) — those are roadmap.

Operationally, this means: if you don't want an agent to publish, don't give it a token. Use MCP clients in flows where the publish step still goes through a human confirming the call.

Common errors

HTTP	error.code	Cause
401	unauthorized	Authorization header missing, token wrong, or no agent token has been minted (open Whet Desktop once to provision it).
403	forbidden	Token is valid but the workspace state forbids the action (e.g. publishing an artifact that's still in draft).
404	not_found	Resource doesn't exist in the workspace bound to this token.

Every response includes the X-Request-Id header. Correlate against local logs by that id; request_id does not appear in the error body. See Errors for the full taxonomy.

Webhook signatures (different scheme)

If you're consuming events from Whet (rather than calling Whet's API), the scheme is different: webhooks arrive HMAC-signed with a shared WEBHOOK_SIGNING_SECRET issued when you enable the public webhook receiver feature (Basic / Pro). See Webhooks · HMAC verification for the algorithm.

Multi-tenant deployments (Team / Enterprise)

Team and Enterprise deployments support multi-seat workspaces with per-user tokens. Tokens are minted from the admin console; revocation is per-token rather than global. The CLI behavior is identical — pass --base-url pointing at your team's host and the same whet auth login flow applies.