Authentication

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

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

After logging in, 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

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.