Authentication

Credentials live in your operating system's keychain — never in config files, never in argv, never echoed to your terminal. The CLI reads and writes them through the keyring library and hands the secret to an Authorization header only at the request boundary. Nothing else touches it.

Where credentials are stored

Every stored secret sits under the keychain service name solwyn-cli, as three separate entries:

Your platform's native secret store backs the keychain:

Two kinds of credential

Solwyn recognizes two credential types, and they authorize different things.

A JWT pair — an access token plus a refresh token — represents you, the logged-in user. You obtain it with solwyn login, which prompts for your email and password on an interactive terminal. When a request returns 401, the CLI refreshes the pair once and retries the request a single time; you do not re-login when an access token expires.

A project key authorizes one project. It has the shape sk_proj_ followed by 64 lowercase hexadecimal characters — validated against the pattern ^sk_proj_[a-f0-9]{64}$ before it is ever stored. You provide it with solwyn login --with-key (a hidden prompt on a terminal, or piped over stdin), or through the SOLWYN_API_KEY environment variable.

Resolution precedence

When a command needs a credential, the CLI resolves one in a fixed order. The first source that yields a value wins:

If none resolve, the command reports that authentication is required and exits with code 3. An environment key always shadows a stored key, and a stored key always shadows a stored JWT pair — set SOLWYN_API_KEY and you act as that project regardless of what the keychain holds.

What each command requires

Some commands act on your whole account and need your user login; some act on a single project and need that project's key; some accept either.

Use the wrong type and the command fails loud with exit code 3 before any request is dispatched: a project-key-only command run under a JWT reports project_key_required; an account command run under a project key reports that user login is required, with a hint to solwyn login.

whoami accepts either credential and reports what that credential can see — under a project key, the local key identity and configured project; under a JWT pair, your account identity and the projects available to you. login, logout, and the config and agent-context commands are local operations and need no stored credential.

Logging in

$ solwyn login
Email: alice@example.com
Password: ********

$ solwyn login --with-key
Project key: ****************

$ echo "$SOLWYN_PROJECT_KEY" | solwyn login --with-key

Logging out

$ solwyn logout

Clears all three keychain entries — api_key, access_token, and refresh_token. Environment variables are not touched; if SOLWYN_API_KEY is set, it still resolves after a logout.

CI, containers, and agents

In pipelines and containers there is usually no keychain backend. Provide a project key through SOLWYN_API_KEY instead — it sits at the top of the resolution order, so it works with no keychain present:

jobs:
  check-budget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install solwyn-cli
      - run: solwyn --project ${{ vars.SOLWYN_PROJECT_ID }} budget status
        env:
          SOLWYN_API_KEY: ${{ secrets.SOLWYN_API_KEY }}

Because budget check and budget confirm require a project key, SOLWYN_API_KEY is exactly the credential automated budget guardrails run on. See Scripting for the machine contract and Agents for wiring guardrails into agent loops.

Checking your state

$ solwyn whoami

Reports which credential resolved, its source (keyring or environment), and — under a JWT pair — your identity and projects. It is the fastest way to confirm which project a given shell will act as.

Next steps

• Configuration — set a default project and API URL in config.toml
• init — one-command onboarding that stores a credential and verifies it end-to-end
• Privacy — the wire contract the SDK and CLI share