Autenticação

:::caution Produtos não compartilham credenciais KOBANA_TOKEN guarda um token OAuth do banking ou um JWT do inbox, dependendo de qual produto você está chamando — nunca os dois ao mesmo tempo. kobana auth login só produz credenciais do banking. :::

banking

Token de acesso (mais simples)

Obtenha o token em Integrações > API > Token de API na interface da Kobana.

export KOBANA_TOKEN=seu_token_aqui

OAuth (PKCE)

O CLI usa OAuth com PKCE — funciona sem configurar nada:

# Login (abre browser, zero config)
kobana auth login

# Login pedindo escopos específicos. Recurso sem verbo é leitura, então esta
# é uma sessão somente de leitura em dois recursos:
kobana auth login --scopes "inbox/emails,inbox/agent_runs"

# Acrescente o verbo global `write` quando a sessão também precisar escrever.
# Não existe escopo `read` nesta API — a lista está na página de Autenticação.
kobana auth login --scopes "inbox/emails,write"

# Client credentials (para apps server-side)
kobana auth login --client-id <ID> --client-secret <SECRET>

# Ver status
kobana auth status

# Exportar credenciais (para CI)
kobana auth export > credentials.json

# Logout
kobana auth logout

Credenciais salvas são criptografadas com AES-256-GCM. A chave fica no keyring do OS (macOS Keychain, etc.) com fallback para arquivo.

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

inbox

O Inbox Autônomo não compartilha credenciais com o banking:

• KOBANA_TOKEN precisa ser um JWT (RS256, emitido pelo Authorization Server da Kobana) cujo aud inclua https://api.inbox[.<env>].kobana.com.br — veja Autenticação da API para entender como esse token é emitido. kobana auth login não gera esse token.
• KOBANA_INBOX_CLIENT_CERT precisa apontar para um arquivo PEM com a cadeia de certificado do cliente e sua chave privada — a API fica atrás de mTLS, exatamente como descrito em Autenticação da API. Sem ele o CLI avisa em stderr e as requisições são recusadas.

kobana inbox emails list --fields "id,subject,received_at"
kobana inbox webhooks deliveries replay \
  --params '{"id": "WEBHOOK_ID", "deliveryId": "DELIVERY_ID"}'

Ambientes

O CLI opera em três ambientes. Produção é o default.

Ambiente	API	OAuth	--env
Produção	api.kobana.com.br	app.kobana.com.br	production (default)
Sandbox	api-sandbox.kobana.com.br	app-sandbox.kobana.com.br	sandbox
Development	localhost:5005/api	localhost:5005	development

# Produção (default — não precisa de flag)
kobana banking charge pix list

# Sandbox
kobana banking charge pix list --env sandbox

# Development local
kobana banking charge pix list --env development

# Via variável de ambiente
export KOBANA_ENVIRONMENT=sandbox
kobana banking charge pix list

# Login em sandbox
kobana auth login --env sandbox

Os tokens são diferentes entre ambientes — um token de sandbox não funciona em produção e vice-versa. Para o inbox, o ambiente vem na claim aud do JWT (inbox/dev, inbox/stg, inbox/sdb, inbox/prd), então o token certo já precisa corresponder ao --env que você passar.

Próximos passos

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