DOCS / CLI

Authentication

A developer runs finowl auth login once and never thinks about it again. A pipeline sets no secret at all. Both reach the right credential without knowing the other exists.

The resolution chain

The credential resolves once per invocation, before any other network call. The order is fixed and the first hit wins.

#	SOURCE	WHO REACHES IT
1	An explicit `--profile`	Anyone naming a profile. A deliberate instruction, never overridden.
2	`FINOWL_TOKEN`	A pre-issued token. The escape hatch for environments the other steps do not cover.
3	`FINOWL_CLIENT_ID` + `FINOWL_CLIENT_SECRET`	A service principal, for CI systems with no OIDC.
4	Ambient CI OIDC exchange	Keyless pipelines. GitHub Actions and GitLab CI are detected natively.
5	The `DEFAULT` profile	A developer who ran `finowl auth login`.

Nothing matches, and the command exits 2 with one authentication error rather than failing later on a pricing call that had no chance of succeeding.

NOTE

A named --profile that has no stored login is an error, not a fallback. The alternative — quietly authenticating as somebody else — is how a run ends up filed against the wrong organization.

Developers: browser login

finowl auth login

Opens a browser, authenticates against your organization's identity provider, and stores the result in a profile. If you belong to more than one organization it asks which one, and remembers the answer.

finowl auth login [OPTIONS]

  -p, --profile TEXT   Profile to sign in as, or out of — e.g. a second
                       organization.  [env: FINOWL_CONFIG_PROFILE; default: DEFAULT]
      --no-browser     Use the device flow: shows a code to enter on another machine.
      --org TEXT       Skip the organization picker by naming one.
      --switch-account Choose the account rather than reusing your browser's session.

Common variations

# a machine with no browser — prints a code to enter elsewhere
finowl auth login --no-browser

# your browser is signed in as the wrong person
finowl auth login --switch-account

# a second organization, kept side by side
finowl auth login --profile acme-eu --org acme-eu

IMPORTANT

finowl auth login refuses to run without a terminal. A pipeline that reaches it has a configuration problem, and waiting on a prompt that will never be answered is the worst way to find out.

Pipelines: keyless OIDC federation

The preferred path, and the one with nothing to rotate. The pipeline proves what it is with a token its own CI system signs; the platform decides what that token may act as. No credential is stored on the CI vendor.

An administrator registers the pipeline once in Settings → CI connections: the repository, the issuer, and which organization its runs act for.
The pipeline grants itself an identity token — permissions: id-token: write on GitHub Actions, an id_tokens: block on GitLab CI.
The CLI detects the token, exchanges it for a platform token, and proceeds. Nothing else is configured.

PROVIDER	DETECTION	WHAT YOU SET
GitHub Actions	Native	`permissions: id-token: write` on the job.
GitLab CI	Native	An `id_tokens:` block exposing the token as `FINOWL_ID_TOKEN`.
Anything else OIDC-capable	Explicit	Set `FINOWL_OIDC_TOKEN` to the identity token. This also overrides detection when it guesses wrong.

Service principals and pre-issued tokens

For CI systems with no OIDC, or for scripts that need a token directly.

# service principal — the platform mints the token
export FINOWL_CLIENT_ID=...
export FINOWL_CLIENT_SECRET=...

# a token you already hold
export FINOWL_TOKEN=...

Both are real secrets with rotation obligations, which is why OIDC federation comes first when it is available.

Environment variables

VARIABLE	EFFECT
FINOWL_HOST	The platform to talk to. Defaults to `https://api.finowl.cloud`. The identity domain, OAuth client id and API audience are discovered from this host, so pointing a pipeline at another environment is this one variable.
FINOWL_CONFIG_PROFILE	The profile to act as, equivalent to `--profile`. Read by every command that has the flag, including the `auth` subcommands.
FINOWL_TOKEN	A pre-issued platform token. Step 2 of the chain.
FINOWL_CLIENT_ID / FINOWL_CLIENT_SECRET	Service principal credentials. Step 3 of the chain.
FINOWL_OIDC_TOKEN	An identity token for a CI system Finowl does not detect natively. Step 4.
FINOWL_HOME	Where profiles and cached tokens are stored.

Inspecting and managing credentials

finowl auth describe

Who you are, where, and which credential is in play. The first thing to run when a command is authenticating as something you did not expect.

$ finowl auth describe
  identity        maya@acme.com
  credential      browser login
  organization    Acme Data Platform
  host            https://api.finowl.cloud
  profile         DEFAULT
  expires         in 8 h (2026-08-20 19:40)

In CI it reports the pipeline identity instead:

  identity        repo:acme/analytics:ref:refs/heads/main
  issuer          https://token.actions.githubusercontent.com
  detected        github_actions
  credential      CI federation
  organization    Acme Data Platform

finowl auth profiles

Every configured profile, its organization, its host and whether its login is still usable.

$ finowl auth profiles
  profile    organization          host                        login
  DEFAULT    Acme Data Platform    https://api.finowl.cloud    active
  acme-eu    Acme EU               https://api.finowl.cloud    expired

Config: /Users/maya/.finowl/config.json

finowl auth token

Prints the current access token and nothing else, for scripting. Errors go to stderr, so $(finowl auth token) never captures an error string and sends it as a bearer header.

curl -H "Authorization: Bearer $(finowl auth token)" \
  https://api.finowl.cloud/api/v1/me/orgs

finowl auth logout

Forgets a stored login and revokes it where possible. A revocation that fails does not stop the local logout — the token expires on its own.

finowl auth logout
finowl auth logout --profile acme-eu

Working across organizations

Profiles exist so one machine can hold several. Each profile stores its own host, organization and token.

finowl auth login --profile acme-eu
finowl breakdown --target prod --profile acme-eu

--profile works on every command that reaches the platform, with -p as its short form everywhere.
FINOWL_CONFIG_PROFILE does the same thing for a whole shell session.
When a finowl.yml belongs to an organization other than the one you are authenticated to, the command stops and names both, rather than reporting into the wrong place.

Next: Common options, or go straight to finowl init.

PREVIOUS

Install and overview

NEXT

Common options