Autenticação

:::caution Produtos não compartilham credenciais KOBANA_TOKEN guarda a credencial de um produto por vez. Um token da Régua de Cobrança não autentica em nenhum outro produto Kobana, e vice-versa. E kobana auth login é só do Gateway Bancário: ele não emite token para a Régua de Cobrança. :::

O token

A Régua de Cobrança autentica com um access token da Conta Kobana: um JWT assinado em RS256 pelo Authorization Server da Kobana (account.kobana.com.br), com aud igual a https://api.dunning.kobana.com.br e exp obrigatória, enviado como Authorization: Bearer <token>. A API só verifica esse token — ela não emite token nenhum. Veja Autenticação da API para como o token é obtido, as claims exigidas e os escopos que ele carrega.

Coloque o token em KOBANA_TOKEN antes de chamar o produto:

export KOBANA_TOKEN=$TOKEN_DUNNING
kobana dunning me list

kobana dunning me list responde quem é o dono do token (usuário e organização) — é o jeito mais rápido de confirmar que a credencial está valendo.

Como a variável é a mesma para todos os produtos, exporte-a por comando (ou use um .env por projeto) se você alterna entre produtos na mesma sessão:

KOBANA_TOKEN=$TOKEN_DUNNING kobana dunning charges list --fields "id,status,current_amount"

Workspace (X-Workspace-Id)

O token identifica a organização; os dados dela ficam em workspaces, e o cabeçalho X-Workspace-Id diz em qual deles a chamada age — o id ou o public_id que aparecem em Workspaces no dashboard (ou em kobana dunning workspaces list). Ele pode ser omitido enquanto a organização tem um único workspace; com dois ou mais, a falta dele responde 400 WORKSPACE_REQUIRED. Um workspace de outra organização (ou um valor que não é UUID) responde 403 UNKNOWN_WORKSPACE. me e workspaces não agem dentro de um workspace e ignoram o cabeçalho.

O CLI preenche o cabeçalho a partir de KOBANA_WORKSPACE_ID. Para agir em outro workspace numa chamada só, passe o cabeçalho em --params, que tem precedência sobre a variável:

kobana dunning workspaces list --fields "id,public_id,name"
export KOBANA_WORKSPACE_ID=WORKSPACE_ID
kobana dunning charges list
kobana dunning charges list --params '{"X-Workspace-Id": "OUTRO_WORKSPACE_ID"}'

O --dry-run mostra os cabeçalhos que seriam enviados (sem o token), e kobana schema lista os cabeçalhos de cada endpoint em header_params. Disponível a partir da versão 0.7.0 do CLI.

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)

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.dunning.kobana.com.br	production (padrão)
Sandbox	api.dunning.sandbox.kobana.com.br	sandbox

A Régua de Cobrança não tem host de desenvolvimento próprio: com --env development o CLI cai em produção.

# Produção (padrão — sem flag)
kobana dunning charges list

# Sandbox
kobana dunning charges list --env sandbox

# Via variável de ambiente
export KOBANA_ENVIRONMENT=sandbox
kobana dunning charges list

Os tokens são diferentes entre ambientes — um token de sandbox não funciona em produção, e vice-versa.

Próximos passos

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