Authentication

Learn how to authenticate with the Komodo Development Kit using either web login (user-based) or machine-to-machine credentials.

Accounts

A Komodo account is your organizational entity on the platform. Each account has its own data subscriptions and a dedicated Komodo-managed Snowflake warehouse. Every query and API operation is scoped to the account you select or pass in.

Account identifiers

• Account ID — UUID that uniquely identifies the account (for example 123e4567-e89b-12d3-a456-426614174000).
• Account slug — Human-readable name (for example my-organization).

Multiple accounts

You can have access to more than one account. Data does not move between accounts; each account is isolated. Use komodo account set (or pass account_id in code) so the SDK knows which warehouse to use.

Authentication Types

The SDK supports two types of authentication:

1. Web Login (User-Based Authentication)

Web login uses a browser-based OAuth flow for interactive user authentication. This method:

• Opens your browser for authentication
• Is intended for individual users
• Provides JWT tokens for API access
• Best for interactive, manual use

Ways to use Web Login:

Via CLI (Persisted)

When you use the CLI, credentials are stored in the [default] profile:

uv run komodo login

This stores the JWT token in ~/.komodo/credentials under [default], which can be used by subsequent SDK calls.

Tip

If the login is associated with a single account, it will be selected automatically. Otherwise, run komodo account set to select your account.

Then use the SDK without passing credentials:

from komodo import get_snowflake_connection

# Uses credentials from [default] profile
conn = get_snowflake_connection()

If no credentials are found, the SDK will trigger a web login flow automatically, but credentials are not persisted to disk. They exist only for that session.

Via SDK (In-Memory Only)

Pass a JWT token directly with an account ID:

from komodo import get_snowflake_connection

jwt = "eyJ0eXAiOiJKV1QiLCJhbGc..."  # From `komodo jwt`
account_id = "123e4567-e89b-12d3-a456-426614174000"  # From `komodo account get`

conn = get_snowflake_connection(jwt=jwt, account_id=account_id)

2. Machine-to-Machine (Service Principal Authentication)

Machine-to-machine (M2M) authentication uses client credentials (client ID and client secret) for automated, non-interactive authentication. This method:

• Uses service principal credentials instead of browser login
• Is designed for automation, CI/CD, and services
• Requires a service principal to be set up in your Komodo account
• Does not require user interaction

Ways to use M2M Authentication:

Via SDK (Explicit Credentials)

Pass credentials directly when creating a connection:

from komodo import get_snowflake_connection

conn = get_snowflake_connection(
    client_id="your_client_id",
    client_secret="your_client_secret",
    account_id="your_account_id",
)

Via Profiles

Store credentials in ~/.komodo/credentials and reference them by profile name.

Setting up Named Profiles:

Create profiles in ~/.komodo/credentials with your service principal credentials:

[default] # Created by `komodo login` and `komodo account set`
token = eyJ0eXAiOiJKV1QiLCJhbGc...
token_expiration = 1234567890
account_id = 123e4567-e89b-12d3-a456-426614174000
account_slug = my-organization

[production]
client_id = client_id_123456
client_secret = client_secret_123456
account_id = 123456789
account_slug = prod-org

[development]
client_id = client_id_234567
client_secret = client_secret_234567
account_id = 234567898
account_slug = dev-org

Using Named Profiles:

from komodo import get_snowflake_connection

# Use a named profile
conn = get_snowflake_connection(profile="production")

# Or use a different profile
conn = get_snowflake_connection(profile="development")

Important Rules:

• You can only use one authentication method at a time
• JWT and explicit M2M credentials require an account_id parameter
• Profiles cannot be combined with account_id - the profile contains the account ID
• You cannot mix methods (e.g., cannot use both jwt and client_id)
• Named profiles only support M2M credentials, not JWT tokens

Valid and Invalid Usage:

# ✅ Valid: Use a profile
conn = get_snowflake_connection(profile="production")

# ✅ Valid: Use explicit credentials
conn = get_snowflake_connection(
    client_id="...",
    client_secret="...",
    account_id="..."
)

# ❌ Invalid: Cannot mix profile with explicit credentials
conn = get_snowflake_connection(
    profile="production",
    client_id="..."  # Error!
)

# ❌ Invalid: Cannot specify account_id with profile
conn = get_snowflake_connection(
    profile="production",
    account_id="..."  # Error! Profile contains account_id
)

Not directly passing to get_snowflake_connection()

If you don’t pass any credentials to SDK functions, the SDK follows this fallback chain:

1. Check [default] profile: Looks for credentials in ~/.komodo/credentials under the [default] section (created by komodo login CLI command)
2. Trigger web login: If [default] is not present or contains invalid/expired credentials, initiates a browser-based login flow
   • Note: When web login is triggered by the SDK (not the CLI), credentials are not persisted to disk. They exist only in memory for that session.

Authentication Precedence

The SDK resolves credentials in the following order:

Precedence Summary:

1. Highest: Explicit credentials passed to the function
   • jwt= + account_id= (Web Login)
   • client_id= + client_secret= + account_id= (M2M)
   • profile= (M2M via named profile)
2. Medium: [default] profile from ~/.komodo/credentials (set by komodo login CLI)
3. Lowest: Web login flow (triggered if no valid credentials found)
   • Note: Credentials from SDK-triggered web login are not persisted to disk

Credentials File Configuration

By default, the Komodo Development Kit (SDK and CLI) store and read credentials from ~/.komodo/credentials. You can customize this location by setting the KOMODO_CREDENTIALS_PATH environment variable.

Default Location

~/.komodo/credentials

Customizing the Path

Set KOMODO_CREDENTIALS_PATH to use a different file path:

macOS / Linux

export KOMODO_CREDENTIALS_PATH="/path/to/my/credentials"

Windows (PowerShell)

$env:KOMODO_CREDENTIALS_PATH = "/path/to/my/credentials"

Once set, all CLI commands (komodo login, komodo account set, etc.) and SDK calls will use this path for reading and writing credentials.

Tip

This is useful when you need to manage multiple credential files, use a shared credentials location, or run in environments where the home directory is not writable.

Example: Using a Custom Credentials Path

macOS / Linux

# Set a custom credentials path
export KOMODO_CREDENTIALS_PATH="/opt/komodo/credentials"

# Login — credentials will be saved to /opt/komodo/credentials
komodo login

# SDK calls will also read from the custom path
python -c "from komodo import get_snowflake_connection; conn = get_snowflake_connection()"

Windows (PowerShell)

# Set a custom credentials path
$env:KOMODO_CREDENTIALS_PATH = "C:\komodo\credentials"

# Login — credentials will be saved to the custom path
komodo login

# SDK calls will also read from the custom path
python -c "from komodo import get_snowflake_connection; conn = get_snowflake_connection()"

Note

If KOMODO_CREDENTIALS_PATH is not set, the default ~/.komodo/credentials is used. The path supports ~ expansion (e.g., ~/custom/credentials will resolve to your home directory).

Provisioning account service principals

Account-scoped service principals provide machine-to-machine (M2M) credentials for automation, CI/CD pipelines, and long-running services. Each service principal belongs to the Komodo account you have selected with komodo account set.

Who can create service principals

Only account administrators can create or delete service principals for an account. If komodo service-principal create returns an access-denied error, your user does not have account admin rights on the currently selected account.

Requesting account administrator access

To provision service principals, you need account administrator rights on the target Komodo account. Contact your organization’s Komodo account administrator to request that access, or ask them who already holds those rights in your account.

Provision a service principal

1. Authenticate with the CLI:

   uv run komodo login

2. Select the account where the service principal should live:

   uv run komodo account set

3. Create the service principal with a descriptive name and description (both required):

   uv run komodo service-principal create --name "my-service" --description "CI pipeline for analytics"

4. Save the client_id and client_secret immediately. The client secret is shown only once. Store both values in your team’s secrets manager or CI secret store.

5. Optional: list or remove service principals in the account:

   uv run komodo service-principal list

   uv run komodo service-principal delete --service-principal-id "<SERVICE_PRINCIPAL_ID>"

Caution

Treat service principal credentials like passwords. Anyone with the client secret can authenticate as that principal for the account it was created in.

Platform role assigned at creation

When a service principal is created, Komodo automatically assigns the platform RBAC role komodo_connector:standard_user. That role provides the baseline permissions needed to use the connector, including Snowflake access through the Komodo data platform.

• You do not choose or customize this role during CLI provisioning.
• Additional account RBAC roles cannot be assigned to a service principal through the CLI today.
• Snowflake access for the principal is provisioned as part of the same create flow; no separate setup step is required on your side.

Note

Human users who work with the connector often need the same komodo_connector:standard_user role on their account. Service principals receive it automatically so automated workloads have equivalent baseline access.

Use the credentials

After provisioning, use the client_id and client_secret with M2M authentication as described in Machine-to-Machine (Service Principal Authentication) above—either by passing them explicitly to get_snowflake_connection() or by adding a named profile in ~/.komodo/credentials.