Authentication

Ringleader uses a multi-origin model: you can federate with one or more control-plane origins and operate across them. The auth commands manage that federation and mint bearer tokens for the HTTP API.

rl auth status

Show the current identity and federated control-plane origins: a “whoami” for the multi-origin model. It is control-plane-optional and never fails on an unreachable origin.

rl auth status
rl auth status -o json        # adds daemon health + per-origin details
rl auth status --show-access  # what you're allowed to do at each origin

When a session expires

An access token that has merely aged out is refreshed silently and you see nothing. But a session can expire terminally — typically after a laptop sleeps long enough that the refresh is rejected outright. The control plane is up and the origin is reachable; only a fresh login fixes it.

rl auth status says so, and names the command to run:

Origins:
  cp1                https://cp.example.com                  logged in  alice@example.com
             warning: session expired — sign in again: rl auth login https://cp.example.com

In -o json, the origin carries "needsReauth": true.

Every other command that reads from that origin reports the same thing rather than a generic failure:

warning: origin "cp1": session expired or not authenticated; run `rl auth login https://cp.example.com`

The macOS app and the Windows tray show a Session expired notice with a Sign in again button that reruns the login against that origin.

An unreachable origin is a different, transient thing and never prompts you to sign in again; nor does a permission denial, which re-authenticating would not fix.

rl auth login <url>

Register a control plane as a federated origin. By default this runs an interactive device-code flow and stores access + refresh tokens.

# Interactive device-code login.
rl auth login https://your-control-plane.example.com

# CI, with no stored secret: become a service account by exchanging
# the job's own workload identity.
rl auth login https://cp.example.com \
    --service-account dev/ci --provider acmecorp-github

# Non-interactive with a static bearer token.
rl auth login https://cp.example.com --token "$RL_TOKEN" --name ci

# Loopback / unauthenticated control plane.
rl auth login http://127.0.0.1:8080 --anonymous

--service-account only works where an ambient workload identity exists — a GitHub Actions job with permissions: {id-token: write}, or the equivalent on another CI platform. On a laptop there is nothing to exchange. See ServiceAccount for the objects it needs.

rl auth logout <origin-name>

Remove a federated control plane by its local name.

rl auth logout ci

rl auth token

Mint a bearer token for the HTTP API, signed with the data dir’s signing key (the same key rl serve verifies with). With no --as, it mints a token for the current user.

rl auth token                       # current user, 1h
rl auth token --as sa:dev/builder --ttl 24h