Autenticação
O CLI resolve o token nesta ordem, e para no primeiro que encontrar:
| Prioridade | Método | Configuração |
|---|---|---|
| 1 | Token direto | KOBANA_TOKEN |
| 2 | Arquivo de credenciais | KOBANA_CREDENTIALS_FILE, um JSON com access_token |
| 3 | Credenciais salvas | kobana auth login |
:::caution Um token por produto
KOBANA_TOKEN guarda a credencial de um produto por vez. Um token do Gateway Bancário não autentica no Faturamento, no Financeiro nem no Inbox, e o contrário também não vale. Se você alterna entre produtos, exporte a variável por comando ou use um .env por projeto.
:::
Login pelo navegador (OAuth com PKCE)
O caminho mais simples para uso interativo. Não precisa configurar nada:
kobana auth login
O CLI abre o navegador na tela de autorização da Kobana e espera o retorno num endereço local (http://127.0.0.1 numa porta livre). Depois que você autoriza, ele guarda o token.
Sem --scopes, o CLI abre um seletor de escopos no terminal, com todos marcados, e pergunta se o acesso é de leitura ou de escrita (leitura vem selecionada). Fora de um terminal interativo, ele pede todos os escopos.
# Pedir só alguns escopos, sem o seletor interativo
kobana auth login --scopes "charge.bank_billets,read"
# Login no sandbox
kobana auth login --env sandbox
# De onde vem o token, o ambiente e, nas credenciais salvas, quando expiram
kobana auth status
# Exportar as credenciais como JSON (para usar em CI com KOBANA_CREDENTIALS_FILE)
kobana auth export > credentials.json
# Apagar as credenciais salvas
kobana auth logout
As credenciais salvas ficam cifradas com AES-256-GCM em credentials.enc, no diretório de configuração. A chave fica no keyring do sistema operacional (Keychain no macOS) e, quando não há keyring, num arquivo ao lado.
O CLI não renova o token salvo sozinho: quando a data de expiração salva passa, o comando falha com erro de autenticação (código de saída 2) e pede um novo kobana auth login. Um token recusado pela API, como um token revogado, sai com 1 (erro 401).
Client credentials, para servidor
Uma aplicação OAuth própria, cadastrada na conta, autentica sem navegador:
kobana auth login --client-id <CLIENT_ID> --client-secret <CLIENT_SECRET>
O fluxo client credentials exige as duas flags. KOBANA_CLIENT_ID e KOBANA_CLIENT_SECRET só valem no login pelo navegador: o ID substitui o padrão kobana-cli, e o secret, opcional, vai na troca do código.
Token direto
Para scripts e CI, use um token de API em KOBANA_TOKEN:
export KOBANA_TOKEN=<token>
kobana banking bank-billets list
Crie o token em Conta Kobana → Tokens e Acesso → Meus Tokens Pessoais → Novo Token Pessoal, com o aplicativo Gateway Bancário e o uso API REST, marcando só os recursos e acessos de que o script precisa. Um token criado com o uso MCP não vale na API, e é recusado. Veja Autenticação da API para os outros tipos de token.
Ambientes
O CLI opera em três ambientes, e produção é o padrão:
| Ambiente | API | --env |
|---|---|---|
| Produção | https://api.kobana.com.br | production (padrão) |
| Sandbox | https://api-sandbox.kobana.com.br | sandbox |
| Desenvolvimento local | http://localhost:5005/api | development |
# Produção (sem flag)
kobana banking bank-billets list
# Sandbox
kobana banking bank-billets list --env sandbox
# Pela variável de ambiente
export KOBANA_ENVIRONMENT=sandbox
kobana banking bank-billets list
Os tokens são diferentes entre ambientes: um token de sandbox não funciona em produção, e o contrário também não.
Próximos passos
- Uso: sintaxe, recursos e exemplos.
- Variáveis de ambiente: a referência completa.