> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate the CLI

> Configure the mka1 CLI with your API key using flags, environment variables, the OS keychain, or a config file — and attach X-On-Behalf-Of for multi-user integrations.

The CLI resolves credentials from four sources, in this order:

| Priority    | Source               | Where it lives                                                     |
| ----------- | -------------------- | ------------------------------------------------------------------ |
| 1 (highest) | Command-line flag    | `--bearer-auth` on any command                                     |
| 2           | Environment variable | `MKA1_BEARER_AUTH` in your shell                                   |
| 3           | OS keychain          | macOS 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:

```bash theme={null}
mka1 --bearer-auth 'Bearer <mka1-api-key>' llm models list
```

## 2. Environment variable

Set the token once in your shell (or CI job):

```bash theme={null}
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.

## 3. OS keychain (recommended for workstations)

Run the interactive login once. The CLI prompts for your API key and writes it to your operating system's secret store:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/docs/authentication) and [deep dive](/docs/authentication-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:

```bash theme={null}
mka1 auth api-keys exchange-token \
  --bearer-auth 'Bearer <mka1-api-key>' \
  --audience https://my-service.example.com \
  --external-user-id user_123
```

The response contains the short-lived JWT you can forward to other services.

## Next steps

* [Commands](/docs/cli/commands) — run your first workflows once you are authenticated.
* [Debug and inspect](/docs/cli/diagnostics) — use `--dry-run` to confirm which credentials and headers would be sent.