Autenticación

:::caution Los productos no comparten credenciales KOBANA_TOKEN guarda la credencial de un producto por vez. Un token de Régua de Cobrança no autentica en ningún otro producto Kobana, y viceversa. Y kobana auth login es solo del Gateway Bancario: no emite token para Régua de Cobrança. :::

El token

Régua de Cobrança autentica con un access token de la Cuenta Kobana: un JWT firmado en RS256 por el Authorization Server de Kobana (account.kobana.com.br), con aud igual a https://api.dunning.kobana.com.br y exp obligatoria, enviado como Authorization: Bearer <token>. La API solo verifica ese token — no emite ninguno. Mira Autenticación de la API para saber cómo obtener el token, qué claims debe llevar y qué scopes carga.

Pon el token en KOBANA_TOKEN antes de llamar al producto:

export KOBANA_TOKEN=$TOKEN_DUNNING
kobana dunning me list

kobana dunning me list responde quién es el dueño del token (usuario y organización) — la forma más rápida de confirmar que la credencial funciona.

Como la variable es la misma para todos los productos, expórtala por comando (o usa un .env por proyecto) si alternas entre productos en la misma sesión:

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

Workspace (X-Workspace-Id)

El token identifica a la organización; sus datos viven en workspaces, y el encabezado X-Workspace-Id dice en cuál actúa la llamada — el id o el public_id que aparecen en Workspaces en el panel (o en kobana dunning workspaces list). Puede omitirse mientras la organización tenga un único workspace; con dos o más, omitirlo responde 400 WORKSPACE_REQUIRED. Un workspace de otra organización (o un valor que no es UUID) responde 403 UNKNOWN_WORKSPACE. me y workspaces no actúan dentro de un workspace e ignoran el encabezado.

El CLI completa el encabezado a partir de KOBANA_WORKSPACE_ID. Para actuar en otro workspace en una sola llamada, pasa el encabezado en --params, que tiene precedencia sobre la variable:

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": "OTRO_WORKSPACE_ID"}'

--dry-run muestra los encabezados que se enviarían (sin el token), y kobana schema lista los encabezados de cada endpoint en header_params. Disponible desde la versión 0.7.0 del CLI.

Prioridad de resolución

Prioridad	Método	Configuración
1	Token directo	KOBANA_TOKEN
2	Archivo de credenciales	KOBANA_CREDENTIALS_FILE
3	Credenciales guardadas	kobana auth login (solo Gateway Bancario)

Ambientes

El CLI opera en tres ambientes, y cada producto tiene sus propios hosts. Producción es el valor por defecto.

Ambiente	API	--env
Producción	api.dunning.kobana.com.br	production (por defecto)
Sandbox	api.dunning.sandbox.kobana.com.br	sandbox

Régua de Cobrança no tiene host de desarrollo propio: con --env development el CLI cae en producción.

# Producción (por defecto — sin flag)
kobana dunning charges list

# Sandbox
kobana dunning charges list --env sandbox

# Vía variable de ambiente
export KOBANA_ENVIRONMENT=sandbox
kobana dunning charges list

Los tokens son diferentes entre ambientes — un token de sandbox no funciona en producción, y viceversa.

Próximos pasos

• Uso — sintaxis, recursos, ejemplos.
• Variables de ambiente — la referencia completa, incluyendo configuración y logs.