Skip to main content
The CLI resolves credentials from four sources, in this order:
PrioritySourceWhere it lives
1 (highest)Command-line flag--bearer-auth on any command
2Environment variableMKA1_BEARER_AUTH in your shell
3OS keychainmacOS Keychain, GNOME Keyring / KWallet, Windows Credential Locker
4 (lowest)Config file~/.config/mka1/config.yaml
Higher-priority sources win when more than one is set. Use flags for one-off commands, env vars for CI, and the keychain for your workstation.

​
1. Command-line flag

Pass credentials directly on any command: 
mka1 --bearer-auth 'Bearer <mka1-api-key>' llm models list

​
2. Environment variable

Set the token once in your shell (or CI job): 
export MKA1_BEARER_AUTH="Bearer <mka1-api-key>"

mka1 llm responses create --model auto --input '"Hello"'
mka1 auth whoami will tag the value as [env] so you can see where it came from. Run the interactive login once. The CLI prompts for your API key and writes it to your operating system’s secret store: 
mka1 auth login
Secrets land in:
  • macOS: Keychain
  • Linux: GNOME Keyring or KWallet (via D-Bus Secret Service)
  • Windows: Credential Locker
If no keychain is available — for example, a headless CI runner — the CLI transparently falls back to the config file. Prefer environment variables in that environment instead. mka1 configure is equivalent to mka1 auth login and additionally prompts for non-secret preferences such as the default server URL.

​
4. Config file

Non-secret defaults (such as server-url) are stored in ~/.config/mka1/config.yaml. When no keychain is available, the token is written there too. Protect the file with filesystem permissions if you rely on that fallback.

​
Inspect the active configuration

mka1 auth whoami (or the top-level alias mka1 whoami) prints every resolved setting and its source, with secret values masked: 
mka1 auth whoami
Source tags:
  • [flag] — passed on the command line.
  • [env] — read from an MKA1_* environment variable.
  • [keyring] — stored by auth login or configure.
  • [config] — read from ~/.config/mka1/config.yaml.
  • [unset] — not configured.

​
Clear stored credentials

Remove every credential from both the keychain and the config file: 
mka1 auth logout
This does not touch environment variables — unset those with unset MKA1_BEARER_AUTH.

​
Act on behalf of an end user

The gateway accepts an optional X-On-Behalf-Of: <external-user-id> header so a single server-side API key can attribute traffic and enforce per-user authorization. Send it with -H on any command: 
mka1 llm responses create \
  --model auto \
  --input '"Summarize the support queue for the past 24 hours."' \
  -H 'X-On-Behalf-Of: user-abc456'
Omit the header when you are calling the API as the owning account rather than a specific end user. See the authentication guide and deep dive for the full header-propagation rules, including how the gateway issues and validates exchange JWTs.

​
Exchange an API key for a JWT

If your downstream systems expect a bearer JWT instead of a raw API key, exchange the key at runtime: 
mka1 auth api-key get-jwt-from-key --bearer-auth 'Bearer <mka1-api-key>'
The response contains the short-lived JWT you can forward to other services.

​
Next steps

  • Commands — run your first workflows once you are authenticated.
  • Debug and inspect — use --dry-run to confirm which credentials and headers would be sent.