Authentication

l4 resolves credentials in a fixed order on every invocation:

1. The --token / -t flag
2. The LEVELFOUR_TOKEN environment variable
3. The OS keychain (populated by l4 auth login)

The first match wins. If none yields a token, the command exits with code 4 (ExitAuthRequired) and prints a hint.

Interactive: browser login

For laptop / dev-machine use, the friendliest path is the browser-based device flow:

l4 auth login

This opens your default browser to the LevelFour sign-in page, completes the device-code exchange, and stores the resulting token in the OS keychain (macOS Keychain, Linux Secret Service via libsecret, Windows Credential Vault). Subsequent commands authenticate transparently.

To force a fresh session even if you're already logged in:

l4 auth login --force

To clear the stored token:

l4 auth logout

CI / scripting: LEVELFOUR_TOKEN

For unattended environments, set LEVELFOUR_TOKEN from a secret:

export LEVELFOUR_TOKEN="l4_live_..."
l4 recommendations list --json

In GitHub Actions:

- name: Run LevelFour CLI
  env:
    LEVELFOUR_TOKEN: ${{ secrets.LEVELFOUR_TOKEN }}
  run: l4 recommendations list --status available --jq '.data.data.items[] | .recommendation_id'

The token never touches the filesystem in this mode.

One-shot override: --token

For ad-hoc commands or running as a different identity:

l4 --token "l4_live_..." recommendations list

The flag wins over both the env var and the keychain. Useful when you have multiple API keys (e.g. service accounts) and don't want to re-login.

Inspect the active session

l4 whoami                  # identity, organization, role, connected accounts
l4 auth status             # which credential source is active
l4 auth status --verify    # additionally validate the token against the API

l4 auth status does not hit the network unless --verify is passed — useful for fast pre-flight checks in scripts.

Token formats

Create or rotate keys in Settings → API Keys in the dashboard, or programmatically via the API Keys endpoints.

Switching API hosts

Point at a non-default API base URL with --api or LEVELFOUR_API:

l4 --api https://api.staging.levelfour.ai whoami

The same auth resolution rules apply — only the base URL changes.

Troubleshooting