Login and sessions

Any active Stoa Markets registration signs in with the same email, password and second factor as the web application. There are no API keys to create. A session lives only in your operating system keychain.

Sign in

Run the command in a terminal. The password prompt needs one, so the command refuses to run inside a pipe or a script. Any command run without a saved session asks you to sign in first, then continues; a bare stoa does the same.

stoa login

Command line access needs a second factor on your account: enroll an authenticator app or a text-message number in the web application under Settings, Security before the first sign-in. The client asks for your email, your password, and the second factor:

• Authenticator app. Enter the six digit code from the app you enrolled in the web application under Settings, Security.
• Text message. If your account is enrolled for SMS codes, the client offers to send one to your enrolled number.

On success the client prints the account, the venue, and when the session ends:

Signed in to prod as [email protected]. Session until <time>; it also ends after a period of inactivity.

Check the session

stoa whoami

This prints the signed in user, the organization, and whether the venue would admit a new request from this account right now. When it would not, the line says why in the venue's own words (for example a bank account to link in Settings, or terms to accept), the same sentence a create would answer with. An account whose registration is not active yet cannot sign in; the client reports Your Stoa Markets registration is not active yet. Finish signing up in the web application, then try again. Finish signing up there, then run the command again.

Sessions

Sessions expire. When a command reports that the session has expired, run stoa login again.

Sign out

stoa logout

This forgets the session stored on this machine. To end every session for your account, including browser sessions on other devices:

stoa logout --everywhere

The client reports whether the venue confirmed the revocation.

Where credentials live

Session tokens are stored in the operating system keychain. The client never writes them to a file, never reads them from environment variables, and never prints them, including with --debug. Without a keychain backend the client refuses to store a session, and stoa login says so before it asks for a password (exit code 6).

Headless Linux, WSL and SSH sessions

The keychain must be running and unlocked in the session the client runs in.

• macOS over SSH. The login keychain is locked in an SSH session. Unlock it first, then sign in:

  security unlock-keychain
  stoa login
  

  Copy

• Linux without a desktop, and WSL. Start a Secret Service keyring (GNOME Keyring or KDE Wallet) in the session and unlock it, for example with gnome-keyring-daemon --unlock inside a D-Bus session, then sign in. A container or a CI runner without one cannot hold a session.

• Windows. The Credential Manager is used; nothing to set up.

Troubleshooting