Laptop login

Sign in as yourself, with no service account. Your session is cached, so later Python processes do not prompt again.

pip install "databaas-utils[local]"
databaas login https://<your-databaas-domain> --profile <name>

https://<your-databaas-domain> is the address you open the portal on. Zitadel (https://auth.<your-databaas-domain>) and the catalog (https://catalog.<your-databaas-domain>) are derived from it, and the portal tells the CLI which client id to sign in with.

Flag	Value
--profile	A name for this environment, for example acme-prod. Optional: it defaults to the first part of the domain. Reuse it with --profile or DATABAAS_PROFILE.
--client-id	Only if databaas login says the portal serves no client id: the client id of the environment's databaas-utils app in Zitadel. Ask your Databaas admin.

The warehouse defaults to databaas-lakehouse. --warehouse, --issuer and --catalog-url override it and the derived addresses, for an environment set up differently.

databaas login opens a browser to sign in and saves the profile, so you run it once per environment. Your session is kept in the OS keychain, or in a private file if none is available. On macOS only the refresh token goes in the Keychain, written through /usr/bin/security so that any Python installation can renew it; the short-lived access token is cached in a private file.

Then, in Python, use the same helpers as in a notebook:

from databaas_utils.user import get_catalog

get_catalog().list_namespaces()

Or, without the helpers:

from databaas_utils import LakehouseSettings, rest_catalog

catalog = rest_catalog(LakehouseSettings.from_profile())

Access must be granted

Signing in registers you with the catalog, so an admin can find you there, but they still have to grant you access to a warehouse or namespace. databaas whoami shows your email and catalog user id (oidc~<sub>) to give them.

Commands

See Command line for all commands. In short:

Command	Does
databaas login URL	Sign in and save a profile
databaas whoami	Show your email and Lakekeeper user id
databaas token	Print a fresh access token (for curl, DuckDB)
databaas logout	Revoke and forget the session
databaas profile list / use NAME / delete NAME	Manage several environments

Profiles live in ~/.config/databaas/config.toml. Select one with --profile NAME or DATABAAS_PROFILE.

Troubleshooting

error: ... serves no /.well-known/databaas-client.json; pass --client-id : The URL is not a Databaas portal that publishes its client id. Check that it is the address you open the portal on. Otherwise ask your Databaas admin for the client id and pass --client-id.

error: '...' is the auth address; pass the portal's base URL instead : You passed the auth. or catalog. address. Pass the portal's address, without that prefix.

The browser shows Errors.App.NotFound : The client id is wrong. A Zitadel app has both an app id and a client id; only the client id works here.

Every new Python process opens the browser again : Your saved session has no refresh token. Run databaas login once more.

A 403 from Lakekeeper : You are signed in but have no grant on that warehouse or namespace. Give an admin the user id from databaas whoami.

Unattended code

LakehouseSettings.from_profile(interactive=False) raises instead of opening a browser when there is no valid session. A scheduled job should use a service account, not this.

Environment variables

Variable	Effect
DATABAAS_PROFILE	Profile to use when none is named
DATABAAS_CONFIG_DIR	Where profiles are stored
DATABAAS_CACHE_DIR	Where the file-based session cache is stored
DATABAAS_TOKEN_STORE	file to skip the OS keychain; keyring to require it off macOS