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:

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):

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:

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:

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:

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:

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 e o 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:

mka1 auth api-key get-jwt-from-key --bearer-auth 'Bearer <mka1-api-key>'

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

​

Próximos passos

• Comandos — execute seus primeiros fluxos de trabalho após autenticar-se.
• Depure e inspecione — use --dry-run para confirmar quais credenciais e cabeçalhos seriam enviados.