Authentication

:::caution Products do not share credentials KOBANA_TOKEN holds the credential of one product at a time. A Kadu Agent token does not authenticate on any other Kobana product, and vice versa. :::

The token

The CLI uses the same Kobana Account access token as the API (RS256, with aud equal to https://api.kadu.ia.br), read from KOBANA_TOKEN and sent as Authorization: Bearer. The rules for the token, scopes and permissions are the API's: see API authentication and Permissions. kobana auth login, which belongs to the Banking Gateway, does not produce this token.

export KOBANA_TOKEN=<token>
kobana kadu me list

kobana kadu me list calls GET /v1/me, the only route without a scope check: use it to test a new token.

Since the variable is the same for every product, if you switch between them in one session, pass the token per command:

KOBANA_TOKEN=$TOKEN_KADU kobana kadu executions list

The CLI also reads a .env file in the folder where you run the command and then the one at ~/.config/kobana/.env (on macOS, ~/Library/Application Support/kobana/.env).

Resolution order

Priority	Method	Setting
1	Direct token	KOBANA_TOKEN
2	Credentials file	KOBANA_CREDENTIALS_FILE
3	Saved credentials	kobana auth login (Banking Gateway only)

Scopes

Ask only for what the use needs, as in the API: kadu/executions for those who only follow runs, kadu/tasks write for those who trigger them, delete only for those who remove. A command outside the scope answers 403 INSUFFICIENT_SCOPE, and the CLI exits with code 1.

Environments

The CLI works in three environments, and each product has its own hosts. Production is the default.

Environment	API	--env
Production	api.kadu.ia.br	production (default)
Development	localhost:3030/api	development

Kadu has no sandbox: --env sandbox ends with an error instead of sending a test to production. The CLI does not point to staging either; for staging, call the API directly (https://api.staging.kadu.ia.br/v1). KOBANA_ENVIRONMENT sets the default environment. A token from one environment is not valid in another.

# production (default)
kobana kadu tasks list

# development
kobana kadu tasks list --env development

# KOBANA_ENVIRONMENT
export KOBANA_ENVIRONMENT=development
kobana kadu tasks list

Good practices

• Never commit the token or the .env that holds it.
• In an AI agent, hand over a token with minimal scopes and a short life: the CLI does everything the token allows.

Next steps

• Usage — syntax, resources, examples.
• Environment variables — the full reference, including configuration and logs.