Authentication
:::caution Products do not share credentials
KOBANA_TOKEN holds one product's credential at a time. A Régua de Cobrança token does not authenticate against any other Kobana product, and vice versa. And kobana auth login belongs to the Banking Gateway only: it does not issue a token for Régua de Cobrança.
:::
The token
Régua de Cobrança authenticates with a Kobana Account access token: a JWT signed in RS256 by Kobana's Authorization Server (account.kobana.com.br), with aud set to https://api.dunning.kobana.com.br and a mandatory exp, sent as Authorization: Bearer <token>. The API only verifies that token — it never issues one. See API Authentication for how to obtain the token, the claims it must carry and its scopes.
Put the token in KOBANA_TOKEN before calling the product:
export KOBANA_TOKEN=$TOKEN_DUNNING
kobana dunning me list
kobana dunning me list returns who owns the token (user and organization) — the quickest way to confirm the credential works.
Since the variable is the same for every product, export it per command (or use a per-project .env) if you switch products in the same session:
KOBANA_TOKEN=$TOKEN_DUNNING kobana dunning charges list --fields "id,status,current_amount"
Workspace (X-Workspace-Id)
The token identifies the organization; its data lives in workspaces, and the X-Workspace-Id header says which one the call acts on — the id or the public_id shown under Workspaces in the dashboard (or by kobana dunning workspaces list). It may be omitted while the organization has a single workspace; with two or more, leaving it out answers 400 WORKSPACE_REQUIRED. A workspace of another organization (or a value that is not a UUID) answers 403 UNKNOWN_WORKSPACE. me and workspaces don't act inside a workspace and ignore the header.
The CLI fills the header from KOBANA_WORKSPACE_ID. To act on another workspace for a single call, pass the header in --params, which takes precedence over the 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": "OTHER_WORKSPACE_ID"}'
--dry-run shows the headers that would be sent (without the token), and kobana schema lists each endpoint's headers under header_params. Available since CLI version 0.7.0.
Resolution priority
| Priority | Method | Configuration |
|---|---|---|
| 1 | Direct token | KOBANA_TOKEN |
| 2 | Credentials file | KOBANA_CREDENTIALS_FILE |
| 3 | Saved credentials | kobana auth login (Banking Gateway only) |
Environments
The CLI operates in three environments, and each product has its own hosts. Production is the default.
| Environment | API | --env |
|---|---|---|
| Production | api.dunning.kobana.com.br | production (default) |
| Sandbox | api.dunning.sandbox.kobana.com.br | sandbox |
Régua de Cobrança has no development host of its own: with --env development the CLI falls back to production.
# Production (default — no flag needed)
kobana dunning charges list
# Sandbox
kobana dunning charges list --env sandbox
# Via environment variable
export KOBANA_ENVIRONMENT=sandbox
kobana dunning charges list
Tokens are different across environments — a sandbox token does not work in production and vice versa.
Next steps
- Usage — syntax, resources, examples.
- Environment variables — the full reference, including config and logging.