Getting Access

WarmHub handles sign-up and sign-in through a hosted login flow — there are no credentials to configure locally. The first time you sign in, your account is created automatically.

Creating an Account

There is no separate registration step. The first time you log in (via the CLI or web app), WarmHub creates your account. Supported sign-in methods include:

• Email and password
• Google
• GitHub
• SSO (SAML/OIDC) — if configured for your organization

Your identity works across the CLI, web app, SDK, and HTTP API.

CLI Authentication

Log in

wh auth login

This opens your browser for a device authorization flow:

1. The CLI displays a verification URL and one-time code.
2. Your browser opens to the login page.
3. You authenticate and confirm the code.
4. The CLI receives a token and saves it to ~/.warmhub/auth.json.

Tokens auto-refresh in the background. You should only need to log in once per machine.

Non-interactive environments (CI, containers, headless servers):

For automation, use a personal access token via the WH_TOKEN environment variable instead of interactive login. See the wh token commands for creating tokens.

If you need to pipe a raw JWT (e.g., from another auth system):

echo "$JWT" | wh auth login --with-token

Piped tokens cannot auto-refresh — you’ll need to provide a new one when it expires. PATs are the preferred approach for most non-interactive use cases.

Check status

wh auth status

Shows your identity, auth method (device flow, piped token, or WH_TOKEN environment variable), and token expiry.

Log out

wh auth logout

Clears saved tokens from ~/.warmhub/auth.json. If WH_TOKEN is set as an environment variable, unset it separately.

The WH_TOKEN Environment Variable

For scripts and automation, set WH_TOKEN to a personal access token or JWT:

export WH_TOKEN=eyJhbGciOi...
wh thing head    # authenticates automatically

WH_TOKEN takes precedence over saved credentials from wh auth login. The CLI checks for it on every command.

Token Types

All API requests authenticate via Bearer tokens in the Authorization header. WarmHub supports three token types:

Type	Obtained via	Use case	Expires
Session JWT	wh auth login or web app sign-in	Interactive use	Short-lived (auto-refreshes)
Personal access token	wh token create or POST /api/pats	Scripts, CI/CD, integrations	30 days default, 1 year max
MCP OAuth token	Automatic (OAuth flow in MCP client)	MCP clients (Claude, Cursor, etc.)	Session-based
Sprite token	Minted automatically per sprite run	Action execution on sprites	Short-lived (configurable TTL)

All token types share a unified validation model — they go through the same server-side JWT verification and permission checking. Sprite tokens are scoped versions of the same token infrastructure used by PATs and session JWTs, optionally restricted via tokenScopes at subscription creation time.

See Personal Access Tokens for creating and managing PATs.

Repository Visibility

Repositories are either public or private. Visibility is set at creation time and can be changed by org administrators.

	Public	Private
Read (queries, HEAD, history)	Anyone — no auth required	Authenticated users only
Write (commits, shape mutations)	Authenticated, repo:write scope	Authenticated, repo:write scope
Manage (subscriptions, credentials)	Authenticated, repo:write scope	Authenticated, repo:write scope
Anonymous requests	Return data normally	Return 404 (not 403, to avoid revealing repo existence)

All writes require authentication regardless of visibility. The difference is purely about read access — public repos are readable by anyone, including unauthenticated HTTP requests and MCP clients.

Next Steps

• Personal Access Tokens — create tokens for scripts and CI/CD
• HTTP API Authentication — PAT endpoint reference
• CLI Commands — full command list including auth and token