Signing in

The console has one administrator, who signs in with a username and a password. The same credential opens both consoles a machine can serve:

The password only signs you in. Approving a gate or another recorded act in the browser takes a registered passkey, never the password — see saphan console device.

First sign-in — setting the credential

Until a credential exists, the console serves nothing. It does not serve itself open: every console route answers 503 and says the console is closed. An unprovisioned console is a closed console.

On a new machine the first-run wizard at /setup sets the credential for you — see First-run setup. The rest of this section is the terminal route, which is also how you rotate it.

Set the credential

The verb asks you for the password, the way passwd does:

$ saphan console admin set --user alice --workspace /path/to/workspace
new console password:
retype new console password:
console admin: credential set for user "alice"

Type it and press Enter. Nothing appears as you type — echo is off. You are asked twice and the two are compared: if they differ, the verb says so and writes nothing, and any credential already on file is left exactly as it was.

Minimum length is 12 characters. The verb prints the username, the file, and the argon2id parameters — never the password and never the digest.

The password is never an argument. There is no --password flag: a command line is readable by every process on the machine through ps, and it is written to your shell history. The password reaches the engine from your keyboard, or — for scripts — from standard input, and from nowhere else.

If you press Ctrl-C at the password prompt, your typing may stay invisible. Echo is off while the verb is asking. It turns echo back on when it finishes, including when it refuses — but a Ctrl-C at the prompt kills the process before it gets there, and the terminal keeps the setting. Your next commands run normally; you just cannot see what you type. One command fixes it:

stty sane

Type it blind and press Enter, or close that terminal and open a new one. Nothing was written: a cancelled prompt leaves whatever was on file exactly as it was.

Scripts and CI. When standard input is not a terminal there is nobody to ask, so the whole of standard input is read as the password (trailing newlines are trimmed). The same 12-character minimum applies:

printf '%s' "$CONSOLE_PASSWORD" | \
  saphan console admin set --user alice --workspace /path/to/workspace

If the verb says it cannot turn your terminal's echo off, it refuses. On a platform the product does not ship binaries for, or on a terminal whose settings it cannot read, you get this instead of a prompt (first line wrapped here to fit the page):

console admin set: STDIN IS A TERMINAL WHOSE ECHO THIS BUILD CANNOT TURN OFF — nothing was
read and nothing was written.
Asking you to type a password here would put it on the screen and into this
terminal's scrollback, so the verb refuses instead of reading it in the clear.
→ feed the password in through a pipe, which never puts it on the screen either:
    read -rs -p 'new console password: ' P && printf '%s' "$P" | saphan console admin set --user <name>; unset P

That refusal is deliberate: the verb will not ask you to type a password onto a screen where it would be visible and would stay in your scrollback. Use the pipe route:

read -rs -p 'new console password: ' P && \
  printf '%s' "$P" | saphan console admin set --user alice --workspace /path/to/workspace
unset P

The shipped binaries are darwin/arm64, linux/amd64 and linux/arm64, and the prompt works on all three; you will normally meet this refusal only in a build from source on another platform.

Confirm what was written

saphan console admin status --workspace /path/to/workspace

Expect console admin: SET, your username, the file at 0600, and the argon2id parameters.

Start the server, or restart it

The current console (saphan-gateway) picks up a first credential without a restart: the next request after you set it finds it.

The projection server does not. It resolves the credential once per process, at the first console request it serves — so a server that has already answered "console: closed — no master-admin credential has been set" goes on answering exactly that after you set one. Start it, or stop it and start it again:

saphan server stop --workspace /path/to/workspace
saphan server start --workspace /path/to/workspace

⚠ The verb's own closing hint prints the start command as saphan server --workspace …; that form is refused with missing subcommand. Use saphan server start.

Sign in

Open the console address in a browser. You are redirected to /console/login — that redirect is the mechanism working. Enter the username and password.

Sign out with the log out button. It is a POST, and it ends the session on the server, not just in your browser.

Signing in day to day

With a live session you land on the console directly. A session lasts 12 hours from sign-in.

Without one — no cookie, an expired one, one from before a restart — you are redirected to the login form, with where you were going carried along, so signing in puts you back there.

A failed sign-in says exactly this, and nothing else:

Wrong username or password.

That message is identical for a wrong password and for a username that does not exist, and both cost the same amount of work, so the timing does not reveal the answer either. The login form is not a way to discover who your administrator is.

After 5 failed attempts from one address within 15 minutes, the next attempt is refused with 429 and a Retry-After, until the oldest of those failures is 15 minutes old. A correct password does not clear a tripped lockout — only time does. Wait it out, or restart the server if you are the one locked out and cannot wait. A burst of simultaneous attempts from one address can also be answered 503 with a two-second Retry-After while earlier attempts are still being checked.

Rotating the credential

Rotate when you suspect exposure, when someone who knew the password leaves, or on whatever schedule your policy sets.

Rotation is two steps, and the second one is the rotation. Writing the new password changes a file on disk. A server that is already running does not read that file again. Until you restart it, the old password still signs in and the new one is refused. If you are rotating because a password is compromised, then until the restart the compromised password is still live — and nothing on the console will tell you so. This holds for both consoles.

1. Set the new password

The same verb as the first time, run against an existing credential. It asks twice, exactly as before:

$ saphan console admin set --user alice --workspace /path/to/workspace
new console password:
retype new console password:
console admin: credential ROTATED for user "alice"

The output says ROTATED, and it repeats the restart requirement on the spot. The old digest is replaced in the file. That is all this step does.

A mistyped retype is safe. If the two entries differ, the verb refuses, writes nothing, and the old password stays on file and keeps working. Run it again.

2. Restart every server that serves a console

This is the step that rotates the password. For the projection server:

saphan server stop --workspace /path/to/workspace
saphan server start --workspace /path/to/workspace

For the current console, stop saphan-gateway and start it again with the arguments you started it with (saphan-gateway stop, then saphan-gateway start --workspace /path/to/workspace …). If the saphan-server daemon serves the projection on this machine, restart that too.

Two things happen here, and both of them are the point:

• The server reads the credential file. A running server holds what it read for the life of the process. Until this restart the old password still signs in, and the new one is refused with the ordinary "Wrong username or password." — which is exactly what a mistyped new password looks like, so the screen cannot tell you which of the two you are looking at.
• Every open session ends. Sessions are held in the server's memory, including the ones issued before the rotation. A restart is the only thing that closes them.

A rotation that stops after step 1 is no rotation at all — the file changed and nothing else did.

saphan server reload is not this step. It re-reads the server's configuration and reports success, but it does not start a new process, so the credential, the sessions and the attempt counters stay as they were. Stop the process and start it again.

3. Confirm — first the file, then the sign-in

saphan console admin status --workspace /path/to/workspace

Then open the console and sign in with the new password. If the new password works, the restart took. If the old password still works, the restart did not happen — the process you are talking to is the one that was running before, still holding the credential it read at start-up.

Why the server does not just reload the file. The credential, the sessions and the attempt counters are resolved together, once per process. Reloading only the credential would make the console say something false in a more dangerous way: the new password would work while the sessions the old one issued — including one held by whoever you are rotating against — stayed open, and the console would look rotated. The restart is what makes all three true at once.