Authentication

Learn how to authenticate with the Komodo SDK 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 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:

export 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

# 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()"

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).

Creating Service Principal Credentials

Create a service principal using the CLI:

uv run komodo service-principal create --name "my-service" --description "My service principal"

You’ll receive a client_id and client_secret to use for authentication.