Authentication: roar and GLaaS

roar supports two paths to authenticate with GLaaS. Pick one based on your environment:

Both surface the same identity to roar register, roar put, and GLaaS itself.

Precedence: if both are configured, the bearer token (from roar auth login) takes precedence. SSH auth is only used when no valid token is present.

roar auth login — browser / device flow

roar auth login      # also available as: roar login

Opens a device-code approval flow in your browser: sign in with GitHub, approve the device, done. The resulting auth token is written to ~/.config/roar/auth.json and shared across every roar workspace on the machine — you don't repeat this per project.

Useful options (same as roar login):

• --force — replace an existing session without prompting.
• --token-file <path> — import a previously exported auth state JSON (e.g., to copy a session to another machine).
• --glaas-api-url <url> — point at a non-default GLaaS instance (rare).

SSH key auth — for CI / headless machines

For environments where the device flow doesn't fit — headless servers, CI jobs, anywhere you can't open a browser — pair a GitHub SSH key with your GLaaS account once, then use it from there:

roar auth key        # print the public key roar will use
# sign in at https://glaas.ai → Account Settings → SSH Keys → paste the key
roar auth status     # verify the pairing works

Which key does roar use? In priority order:

1. ROAR_SSH_KEY environment variable (path to private key, without .pub)
2. glaas.key config value (roar config set glaas.key ~/.ssh/mykey)
3. Auto-discovered from ~/.ssh/ — tries id_ed25519, id_rsa, id_ecdsa in that order

The source is shown in roar auth status output and in roar auth key.

Check auth status

roar auth status

Shows which method is active, tests credentials against the server, and tells you what to do if something isn't working — modelled after gh auth status.

Example output when fully authenticated via browser login:

Server: https://api.glaas.ai  ✓ reachable

Bearer token (roar login / roar auth login):
  ✓ Logged in as alice <alice@example.com>
    Expires: 2026-09-01T00:00:00Z
  ✓ Token accepted by server

SSH key (roar auth key):
  ✓ Key: /home/alice/.ssh/id_ed25519  (auto-discovered from ~/.ssh)
    Fingerprint: SHA256:abc123...
  ✗ Key not registered with GLaaS
    Register at: https://glaas.ai/login → Account Settings → SSH Keys

Active method: bearer token

Sign out

roar auth logout     # also available as: roar logout

Revokes and removes the token stored in ~/.config/roar/auth.json.

To stop using SSH key auth: since bearer token already takes precedence, the simplest path is roar auth login. To fully disable SSH auth, remove the key from your GLaaS account at glaas.ai (the on-disk key is yours; GLaaS just stops accepting it). To pin which key roar uses, set glaas.key in config or ROAR_SSH_KEY in the environment.

After authentication

Logging in (either path) does one more thing besides storing identity: if your workspace is still at the init default anonymous scope, it auto-flips to private. From that point your roar register / roar put publishes are access-controlled rather than public-by-default. Override per-workspace with roar scope use <…>. See Scopes for the full visibility model.

See also

• Scopes — how authentication interacts with workspace visibility (anonymous / private / public / project).
• Troubleshooting — the "Registration / scope / auth" section covers Stored auth state at <path> is not valid JSON, scope-binding errors, and related failures.
• roar Guide — the wider CLI surface for register, put, whoami, and the other commands that consume auth state.