Authentication
Overlord supports two ways to authenticate a surface: OAuth and user tokens. Which one you reach for depends on where the surface runs and whether it can complete an interactive browser flow.
The two methods
- OAuth — an interactive, browser-based login. The resulting session is shared across Overlord Desktop and the CLI on the same machine, and it expires and refreshes like a normal user session. Best when a human can complete a consent screen and the surface runs on a trusted local machine.
- User token (USER_TOKEN) — a durable, per-user bearer token (prefixed
out_) created in Settings → Tokens or withovld user-token create. It requires no browser flow, which makes it the right choice for headless, cloud, or CI environments — and for any CLI that runs separately from Overlord Desktop.
How to choose
| Situation | Use |
|---|---|
| Overlord Desktop on your machine | OAuth |
| CLI on the same machine as Desktop | OAuth (shared session) |
| CLI in a separate container or remote target | User token |
| Cloud / hosted agent over MCP, OAuth-capable runtime | OAuth |
| Cloud / hosted agent over MCP, OAuth unreliable | User token |
What every method shares
- Requests are scoped to a workspace. Mission display ids like
1:1263are<workspace>:<sequence>, so mission-scoped commands infer scope automatically from the id. - Credentials live locally — in shared Desktop/CLI credential files for OAuth, or in environment variables / saved CLI credentials for user tokens. Overlord never asks you to paste a long-lived secret into the web app.
- If a CLI or protocol call returns
401, runovld auth repairfirst, thenovld auth loginif repair does not resolve it.