> ## 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.

# Autenticar o CLI

> Configure o mka1 CLI com sua chave de API usando flags, variáveis de ambiente, o keychain do sistema operacional ou um arquivo de configuração — e anexe X-On-Behalf-Of para integrações multiusuário.

O CLI resolve as credenciais a partir de quatro fontes, nesta ordem:

| Prioridade     | Fonte                           | Onde está armazenado                                                  |
| -------------- | ------------------------------- | --------------------------------------------------------------------- |
| 1 (mais alta)  | Flag de linha de comando        | `--bearer-auth` em qualquer comando                                   |
| 2              | Variável de ambiente            | `MKA1_BEARER_AUTH` no seu shell                                       |
| 3              | Keychain do sistema operacional | Keychain do macOS, GNOME Keyring / KWallet, Windows Credential Locker |
| 4 (mais baixa) | Arquivo de configuração         | `~/.config/mka1/config.yaml`                                          |

Fontes de maior prioridade prevalecem quando mais de uma está definida. Use flags para comandos pontuais, variáveis de ambiente para CI e o keychain para sua estação de trabalho.

## 1. Flag de linha de comando

Passe as credenciais diretamente em qualquer comando:

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

## 2. Variável de ambiente

Defina o token uma vez no seu shell (ou job de CI):

```bash theme={null}
export MKA1_BEARER_AUTH="Bearer <mka1-api-key>"

mka1 llm responses create --model meetkai:functionary-pt --input '"Hello"'
```

`mka1 auth whoami` marcará o valor como `[env]` para que você veja de onde ele veio.

## 3. Keychain do sistema operacional (recomendado para estações de trabalho)

Execute o login interativo uma vez. O CLI solicitará sua chave de API e a gravará no armazenamento de segredos do seu sistema operacional:

```bash theme={null}
mka1 auth login
```

Os segredos são armazenados em:

* **macOS**: Keychain
* **Linux**: GNOME Keyring ou KWallet (via D-Bus Secret Service)
* **Windows**: Credential Locker

Se nenhum keychain estiver disponível — por exemplo, em um runner de CI sem interface gráfica — o CLI recai automaticamente para o arquivo de configuração. Prefira variáveis de ambiente nesse ambiente.

`mka1 configure` é equivalente a `mka1 auth login` e, adicionalmente, solicita preferências não secretas, como a URL padrão do servidor.

## 4. Arquivo de configuração

Padrões não secretos (como `server-url`) são armazenados em `~/.config/mka1/config.yaml`.
Quando não há keychain disponível, o token também é gravado lá. Proteja o arquivo com permissões do sistema de arquivos se você depender desse fallback.

## Inspecionar a configuração ativa

`mka1 auth whoami` (ou o atalho de nível superior `mka1 whoami`) imprime todas as configurações resolvidas e sua origem, com valores secretos mascarados:

```bash theme={null}
mka1 auth whoami
```

Tags de origem:

* `[flag]` — passada na linha de comando.
* `[env]` — lida de uma variável de ambiente `MKA1_*`.
* `[keyring]` — armazenada por `auth login` ou `configure`.
* `[config]` — lida de `~/.config/mka1/config.yaml`.
* `[unset]` — não configurada.

## Limpar credenciais armazenadas

Remova todas as credenciais tanto do keychain quanto do arquivo de configuração:

```bash theme={null}
mka1 auth logout
```

Isso não afeta variáveis de ambiente — desfaça-as com `unset MKA1_BEARER_AUTH`.

## Agir em nome de um usuário final

O gateway aceita um cabeçalho opcional `X-On-Behalf-Of: <external-user-id>` para que uma única chave de API do lado do servidor possa atribuir o tráfego e impor autorização por usuário. Envie-o com `-H` em qualquer comando:

```bash theme={null}
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Summarize the support queue for the past 24 hours."' \
  -H 'X-On-Behalf-Of: user-abc456'
```

Omitir o cabeçalho quando você estiver chamando a API como a conta proprietária, e não como um usuário final específico.

Veja o [guia de autenticação](/pt/docs/authentication) e o [deep dive](/pt/docs/authentication-deep-dive) para todas as regras de propagação de cabeçalhos, incluindo como o gateway emite e valida JWTs de troca.

## Trocar uma chave de API por um JWT

Se seus sistemas downstream esperam um JWT bearer em vez de uma chave de API bruta, troque a chave em tempo de execução:

```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
```

A resposta contém o JWT de curta duração que você pode encaminhar para outros serviços.

## Próximos passos

* [Comandos](/pt/docs/cli/commands) — execute seus primeiros fluxos de trabalho após autenticar-se.
* [Depure e inspecione](/pt/docs/cli/diagnostics) — use `--dry-run` para confirmar quais credenciais e cabeçalhos seriam enviados.