OAuth login walkthrough

mockarty-cli auth login is the recommended way to authenticate a CLI
session against a Mockarty admin node. It performs OIDC discovery, runs the
RFC 8628 OAuth Device Flow
when the server advertises it, and falls back to API-token entry otherwise.

The flow is designed to work in three situations:

1. Local workstation with a browser. Default. The CLI opens your
   browser to the verification URL; you approve there; the CLI receives a
   token and writes it to ~/.mockarty/auth.json.
2. Self-hosted / company Mockarty. Identical flow, except you point at
   https://mockarty.company.com with --server.
3. Headless / SSH session. The CLI detects there is no GUI and prints
   the verification URL plus a short user code. Open the URL on a
   workstation, approve, and the CLI continues automatically.

Quick start

mockarty-cli auth login --server https://mockarty.company.com

If you don’t pass --server, the CLI reads — in order — MOCKARTY_SERVER
from the environment and the server_url field of ~/.mockarty/config.yaml.

After a successful login the CLI prints something like:

✓ Logged in as alice@company.com (https://mockarty.company.com)
  Run any mockarty-cli command to start using the full feature surface.

Step-by-step walkthrough

1. Discovery

The CLI calls GET <server>/.well-known/openid-configuration to find out
which auth grants the server supports. If the server doesn’t speak OIDC at
all (404, connection refused, malformed JSON) the CLI falls back to the
API-token paste flow — see Fallback: API token.

→ Discovering authentication endpoints…

2. Device code request

If the server advertises the urn:ietf:params:oauth:grant-type:device_code
grant, the CLI POSTs to the device-authorization endpoint and receives:

• device_code — opaque, kept by the CLI.
• user_code — eight-character grouped code (XXXX-XXXX) that humans type.
• verification_uri / verification_uri_complete — where to approve.
• expires_in — typically 600 s.
• interval — minimum poll interval (default 5 s).

The CLI then prints:

Your one-time code is: ABCD-EFGH
Open in a browser: https://mockarty.company.com/oauth/device?user_code=ABCD-EFGH
The code expires in 600 seconds.

3. Browser approval

On a workstation with a GUI the CLI tries to open the
verification_uri_complete (which embeds the user code) in your default
browser. If the browser launcher fails or you pass --no-browser, the CLI
prints a Paste the URL into a browser to continue. hint and waits.

In the browser you’ll:

1. Authenticate with your identity provider (Google, VK, Yandex, or the
   server’s local password DB — depends on what the admin configured).
2. Land on the device-approval page and confirm the user code matches what
   the CLI showed.
3. Click Approve.

4. Polling

While the browser dance happens, the CLI polls the token endpoint at the
server-supplied interval (typically every 5 s):

⠋ Waiting for browser approval…

The spinner runs on TTYs; non-TTY callers (CI, captured output) see a
single plain line and dotted progress. Polling stops on any of:

• Approved → CLI receives access_token, decodes the bound identity,
  writes the token to ~/.mockarty/auth.json.
• Denied → the CLI exits with OAuth device flow failed: access_denied
  and exit code 3.
• Expired → after expires_in seconds the device code becomes invalid;
  re-run auth login.

5. Persisting credentials

On success the CLI writes:

• ~/.mockarty/auth.json — token, format mk_…, mode 0600.
• ~/.mockarty/config.yaml — server_url: … (if not already set).
• Optionally namespace: … — when you passed --namespace.

Headless / SSH fallback

There are two ways the CLI detects “no GUI”:

1. --no-browser is passed explicitly.
2. The CLI is connected to a non-TTY stdin OR the OS reports no GUI
   session available (no DISPLAY on Linux, no Aqua session on macOS).

In both cases the CLI prints the verification URL plus the user code and
waits. Open the URL on a workstation that does have a browser, approve, and
the CLI continues. The user code is short enough to dictate over the phone.

ssh server-without-browser
$ mockarty-cli auth login --server https://mockarty.company.com --no-browser

Your one-time code is: ABCD-EFGH
Open in a browser: https://mockarty.company.com/oauth/device
Waiting for browser approval…

Command reference

mockarty-cli auth login [flags]

Flags:
  --server string       Mockarty server URL (overrides config)
  --client-id string    OAuth client identifier (default: built-in CLI client)
  --no-browser          Print verification URL instead of opening a browser
  --namespace string    Active namespace to persist after login
  --insecure            Skip TLS verification (also obeys the global --insecure flag)
  --name string         Context name (reserved for future use)

Logout

mockarty-cli logout

Removes the token from ~/.mockarty/auth.json and leaves the server URL
intact (so a subsequent auth login doesn’t need --server again).

Status check

To check which user the server recognises, open the auth screen:

mockarty-cli tui auth

To check whether the server is healthy, run:

mockarty-cli health

The TUI shows your login, role, server URL, and active namespace after a
successful identity check. health checks the server’s health, not whether
your token is valid; use it as a connectivity pre-check in CI.

Multiple servers

auth login stores one OAuth or pasted token in ~/.mockarty/auth.json and
one server URL in config.yaml. Its --name option does not create a named
profile. For separate interactive OAuth sessions, set MOCKARTY_AUTH_FILE
and MOCKARTY_CONFIG to different paths for each environment, or sign in again when you
switch servers.

If you already have API tokens for several servers, use the CLI’s named
contexts instead:

mockarty-cli login --server https://staging.example.com --token "$STAGING_TOKEN" --name staging
mockarty-cli login --server https://production.example.com --token "$PRODUCTION_TOKEN" --name production
mockarty-cli config get-contexts
mockarty-cli config use-context staging

You can also set MOCKARTY_API_TOKEN and MOCKARTY_SERVER per shell session
for unattended runs. Keep production credentials out of shared scripts and
shell history.

Fallback: API token

If discovery fails or the server doesn’t advertise the device-code grant,
the CLI prompts:

This server does not advertise OAuth device flow.
Paste an API token (mk_…):

You can generate an API token in the admin UI under Settings → Tokens
(or via POST /api/v1/auth/tokens for CI use). Paste the mk_… string;
the CLI persists it identically to an OAuth-issued token.

For unattended CI it’s usually simpler to set MOCKARTY_API_TOKEN on the
runner environment — auth login is interactive and not designed for
non-TTY callers.

Troubleshooting

Security notes

• The token in auth.json is a bearer credential — anyone with read access
  to the file can act as you. The CLI writes it with mode 0600 and the
  parent directory ~/.mockarty/ with mode 0700. Don’t ship it in
  container images.
• Tokens are scoped server-side: an admin token grants admin actions,
  a user token grants only the user’s namespaces and features. The CLI
  cannot widen the token’s authority.
• --insecure disables TLS verification only for the OAuth client; it
  does NOT propagate to subsequent API calls — they read the global
  --insecure flag separately. Don’t run --insecure against production.

Fallback: password login when the provider is unavailable

If you normally sign in through an external provider (Google, VK, Yandex) and
the provider becomes unreachable — a regional block, a corporate firewall, an
IdP outage — you can keep a local password as a backup:

1. While signed in, open your avatar menu (top right) → Profile.
2. If your account has no password yet, the Set Password form is shown —
   set one (minimum 8 characters).
3. From then on the login form accepts your login or your email address
   plus this password, with no provider involved.

The email must be attached to exactly one account; the address you signed in
with through the provider is filled in automatically.