Autenticação

:::caution Produtos não compartilham credenciais KOBANA_TOKEN guarda a credencial de um produto por vez. Um token do Agente Kadu não autentica em nenhum outro produto Kobana, e vice-versa. :::

O token

O CLI usa o mesmo access token da Conta Kobana que a API (RS256, com aud igual a https://api.kadu.ia.br), lido de KOBANA_TOKEN e enviado como Authorization: Bearer. As regras do token, dos escopos e das permissões são as da API: veja Autenticação da API e Permissões. kobana auth login, que é do Gateway Bancário, não produz esse token.

export KOBANA_TOKEN=<token>
kobana kadu me list

kobana kadu me list chama GET /v1/me, a única rota sem checagem de escopo: use-o para testar um token novo.

Como a variável é a mesma para todos os produtos, quem alterna entre eles na mesma sessão passa o token por comando:

KOBANA_TOKEN=$TOKEN_KADU kobana kadu executions list

O CLI também lê um arquivo .env na pasta onde você roda o comando e, depois, o de ~/.config/kobana/.env (no macOS, ~/Library/Application Support/kobana/.env).

Prioridade de resolução

Prioridade	Método	Configuração
1	Token direto	KOBANA_TOKEN
2	Arquivo de credenciais	KOBANA_CREDENTIALS_FILE
3	Credenciais salvas	kobana auth login (só Gateway Bancário)

Escopos

Peça só o que o uso precisa, como na API: kadu/executions para quem só acompanha, kadu/tasks write para quem dispara, delete só para quem apaga. Um comando fora do escopo responde 403 INSUFFICIENT_SCOPE, e o CLI termina com o código de saída 1.

Ambientes

O CLI opera em três ambientes, e cada produto tem os seus próprios hosts. Produção é o padrão.

Ambiente	API	--env
Produção	api.kadu.ia.br	production (padrão)
Desenvolvimento	localhost:3030/api	development

O Kadu não tem sandbox: --env sandbox termina com erro, em vez de mandar um teste para produção. O CLI também não aponta para staging; para staging, use a API diretamente (https://api.staging.kadu.ia.br/v1). KOBANA_ENVIRONMENT define o ambiente padrão. Um token de um ambiente não vale em outro.

# production (default)
kobana kadu tasks list

# development
kobana kadu tasks list --env development

# KOBANA_ENVIRONMENT
export KOBANA_ENVIRONMENT=development
kobana kadu tasks list

Boas práticas

• Nunca versione o token nem o .env que o carrega.
• Num agente de IA, entregue um token com os escopos mínimos e de vida curta: o CLI faz tudo o que o token permite.

Próximos passos

• Uso — sintaxe, recursos, exemplos.
• Variáveis de ambiente — a referência completa, incluindo configuração e logs.