Configure snowflake auth

To configure how PyRel creates a Snowpark session for Snowflake, set the authenticator field on a Snowflake connection and provide the required fields for that authenticator.

The sections below show how to configure each authentication method in a raiconfig.yaml file and in Python code. See the API reference for details on the authenticator field and the required fields for each authentication method.

Note

If you omit the authenticator field on a Snowflake connection, PyRel defaults it to username/password authentication.

Before you start, make sure that:

• You have access to a Snowflake account with the RelationalAI Native App installed. If you are unsure, contact your Snowflake administrator.
• You have working PyRel installation. See Set Up Your Environment for instructions.

Configure username/password authentication

Username/password authentication signs in to Snowflake using your user and password. Use it when you sign in to Snowflake with a password. It is the default when authenticator is omitted.

raiconfig.yaml

Set authenticator to username_password and provide the required fields:

connections:
  sf:
    type: snowflake
    authenticator: username_password
    account: my_account
    warehouse: my_warehouse
    user: my_user
    password: ${SNOWFLAKE_PASSWORD}

Note that:

• Set SNOWFLAKE_PASSWORD in your environment before running Python.
• If you have exactly one connection, default_connection can be omitted.

Programmatic

Use the UsernamePasswordAuth config class or a plain Python dict:

1. Create the config with a typed auth class:

   import os
   
   from relationalai.config import UsernamePasswordAuth, create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": UsernamePasswordAuth(
               account="my_account",
               warehouse="my_warehouse",
               user="my_user",
               password=os.environ["SNOWFLAKE_PASSWORD"],
           ),
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

2. Alternatively, create the config with a dict:

   import os
   
   from relationalai.config import create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": {
               "type": "snowflake",
               "authenticator": "username_password",
               "account": "my_account",
               "warehouse": "my_warehouse",
               "user": "my_user",
               "password": os.environ["SNOWFLAKE_PASSWORD"],
           },
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

Note that:

• Keep your SNOWFLAKE_PASSWORD out of source control.
• Use os.environ["..."] to fail fast when the variable is missing.

Configure username/password authentication with MFA

Username/password MFA authentication supports Snowflake accounts that require multi-factor authentication (MFA). Set authenticator to username_password_mfa, provide user and password, and optionally provide passcode depending on your MFA method. PyRel forwards MFA settings to Snowpark and does not validate your passcode.

You WILL need to provide a passcode when:

• Your MFA flow requires a code (for example, a time-based one-time passcode (TOTP) from an authenticator app).
• You are not using a Duo Push prompt.

You WILL NOT need to provide a passcode when:

• Your MFA flow shows a Duo Push prompt. In this case, omit passcode and approve the prompt.

For more information on MFA, see Snowflake’s Multi-factor authentication (MFA) documentation.

raiconfig.yaml

Set authenticator to username_password_mfa and provide the required fields:

connections:
  sf:
    type: snowflake
    authenticator: username_password_mfa
    account: my_account
    warehouse: my_warehouse
    user: my_user
    password: ${SNOWFLAKE_PASSWORD}
    passcode: ${SNOWFLAKE_PASSCODE}  # Optional, only set if your MFA method requires it

Note that:

• Omit passcode unless your MFA method requires a code.
• Generate a new passcode immediately before you run Python.
• Set SNOWFLAKE_PASSWORD (and SNOWFLAKE_PASSCODE when used) in your environment before running Python.
• If session creation fails and you used a passcode, generate a new passcode and retry.

Programmatic

Use the UsernamePasswordMFAAuth config class or a plain Python dict:

1. Create the config with a typed auth class:

   import os
   
   from relationalai.config import UsernamePasswordMFAAuth, create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": UsernamePasswordMFAAuth(
               account="my_account",
               warehouse="my_warehouse",
               user="my_user",
               password=os.environ["SNOWFLAKE_PASSWORD"],
               passcode=os.getenv("SNOWFLAKE_PASSCODE"),  # Optional, only set if your MFA method requires it
           ),
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

2. Alternatively, create the config with a dict:

   import os
   
   from relationalai.config import create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": {
               "type": "snowflake",
               "authenticator": "username_password_mfa",
               "account": "my_account",
               "warehouse": "my_warehouse",
               "user": "my_user",
               "password": os.environ["SNOWFLAKE_PASSWORD"],
               "passcode": os.getenv("SNOWFLAKE_PASSCODE"),  # Optional, only set if your MFA method requires it
           },
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

Note that:

• If SNOWFLAKE_PASSCODE is unset, passcode is omitted.
• Store secrets in environment variables or a secret manager.
• If session creation fails and you used a passcode, generate a new passcode and retry.

Configure OAuth authentication

OAuth authentication signs in to Snowflake using an OAuth access token. Use it when you already have an OAuth token from your identity provider. PyRel does not acquire, refresh, or validate OAuth tokens.

For more information about Snowflake OAuth and External OAuth, see Snowflake’s Introduction to OAuth. For Python-specific connection parameters, see Snowflake’s Connecting with OAuth documentation.

raiconfig.yaml

Set authenticator to oauth and provide the required fields:

connections:
  sf:
    type: snowflake
    authenticator: oauth
    account: my_account
    warehouse: my_warehouse
    token: ${SNOWFLAKE_OAUTH_TOKEN}

Note that:

• Token acquisition and refresh are managed outside PyRel.
• The token value must be a valid OAuth access token.
• Keep SNOWFLAKE_OAUTH_TOKEN out of your config file.
• If session creation fails with an authentication error, refresh the token and retry.

Programmatic

Use the OAuthAuth config class or a plain Python dict:

1. Create the config with a typed auth class:

   import os
   
   from relationalai.config import OAuthAuth, create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": OAuthAuth(
               account="my_account",
               warehouse="my_warehouse",
               token=os.environ["SNOWFLAKE_OAUTH_TOKEN"],
           ),
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

2. Alternatively, create the config with a dict:

   import os
   
   from relationalai.config import create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": {
               "type": "snowflake",
               "authenticator": "oauth",
               "account": "my_account",
               "warehouse": "my_warehouse",
               "token": os.environ["SNOWFLAKE_OAUTH_TOKEN"],
           },
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

Note that:

• Rotate the token outside PyRel.
• Recreate the Snowpark session after rotating tokens.
• Restart your Python process or clear the session cache programmatically.
• If session creation fails with an authentication error, refresh the token and retry.

Configure key-pair authentication

Use this when you authenticate to Snowflake with a private key (JWT). Set authenticator to jwt and provide a private key file via private_key_path. Snowflake must have the matching public key registered on the user.

For key generation, user configuration, and rotation, see Snowflake’s Key-pair authentication and key-pair rotation documentation. For Python-specific connection parameters, see Snowflake’s Using key-pair authentication and key-pair rotation documentation.

raiconfig.yaml

Set authenticator to jwt and provide the required fields:

connections:
  sf:
    type: snowflake
    authenticator: jwt
    account: my_account
    warehouse: my_warehouse
    user: my_user
    private_key_path: /path/to/key.pem
    private_key_passphrase: ${SNOWFLAKE_PRIVATE_KEY_PASSPHRASE}  # Optional, only set if your key is encrypted

Note that:

• If your key is not encrypted, omit private_key_passphrase.
• The passphrase is used to decrypt the local private key.
• The key file is read when the Snowpark session is created.
• Keep the key file out of source control and restrict file permissions.

Programmatic

Use the JWTAuth config class or a plain Python dict:

1. Create the config with a typed auth class:

   import os
   
   from relationalai.config import JWTAuth, create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": JWTAuth(
               account="my_account",
               warehouse="my_warehouse",
               user="my_user",
               private_key_path="/path/to/key.pem",
               private_key_passphrase=os.getenv("SNOWFLAKE_PRIVATE_KEY_PASSPHRASE"),
           ),
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

2. Alternatively, create the config with a dict:

   import os
   
   from relationalai.config import create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": {
               "type": "snowflake",
               "authenticator": "jwt",
               "account": "my_account",
               "warehouse": "my_warehouse",
               "user": "my_user",
               "private_key_path": "/path/to/key.pem",
               "private_key_passphrase": os.getenv("SNOWFLAKE_PRIVATE_KEY_PASSPHRASE"),
           },
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

Note that:

• Ensure the process can read private_key_path at runtime.
• If the key is encrypted, set SNOWFLAKE_PRIVATE_KEY_PASSPHRASE before creating a session.
• If session creation fails with an authentication error, confirm that the user’s public key is configured in Snowflake.

Configure external browser authentication

Use this to authenticate via an interactive browser sign-in flow. This is a good option when you have MFA requirements but don’t want to manage passcodes in your config. This is NOT a good option for non-interactive environments such as scheduled jobs or CI.

raiconfig.yaml

Set authenticator to externalbrowser and provide the required fields:

connections:
  sf:
    type: snowflake
    authenticator: externalbrowser
    account: my_account
    warehouse: my_warehouse
    user: my_user

Note that:

• This authenticator requires an interactive browser session.
• Restart your Python process or clear the session cache to trigger the browser flow again if you need to re-authenticate.

Programmatic

Use the ExternalBrowserAuth config class or a plain Python dict:

1. Create the config with a typed auth class:

   from relationalai.config import ExternalBrowserAuth, create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": ExternalBrowserAuth(
               account="my_account",
               warehouse="my_warehouse",
               user="my_user",
           ),
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

2. Alternatively, create the config with a dict:

   from relationalai.config import create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": {
               "type": "snowflake",
               "authenticator": "externalbrowser",
               "account": "my_account",
               "warehouse": "my_warehouse",
               "user": "my_user",
           },
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

Note that:

• Run this in an environment that can launch a browser.
• Restart your Python process or clear the session cache to trigger the browser flow again if you need to re-authenticate.

Configure programmatic access token authentication

Programmatic access token authentication signs in to Snowflake using a programmatic access token. Use it when you already have a token issued by Snowflake. PyRel does not issue, rotate, or validate these tokens.

raiconfig.yaml

Set authenticator to programmatic_access_token and provide the required fields:

connections:
  sf:
    type: snowflake
    authenticator: programmatic_access_token
    account: my_account
    warehouse: my_warehouse
    token: ${SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN}

Note that:

• Token issuance and rotation are managed outside PyRel.
• Keep SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN out of your config file.

Programmatic

Use the ProgrammaticAccessTokenAuth config class or a plain Python dict:

1. Create the config with a typed auth class:

   import os
   
   from relationalai.config import ProgrammaticAccessTokenAuth, create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": ProgrammaticAccessTokenAuth(
               account="my_account",
               warehouse="my_warehouse",
               token=os.environ["SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN"],
           ),
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

2. Alternatively, create the config with a dict:

   import os
   
   from relationalai.config import create_config
    from relationalai.semantics import Model
   
   cfg = create_config(
       default_connection="sf",
       connections={
           "sf": {
               "type": "snowflake",
               "authenticator": "programmatic_access_token",
               "account": "my_account",
               "warehouse": "my_warehouse",
               "token": os.environ["SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN"],
           },
       },
   )
   
   # Use the config
   m = Model("MyModel", config=cfg)

Note that:

• Recreate the Snowpark session after rotating tokens.
• Store the token in an environment variable or secret manager.

Define multiple connections

Define multiple connections when you need separate Snowflake configurations in the same project (for example, dev vs prod). When you have more than one connection, set default_connection so PyRel can choose a default.

raiconfig.yaml

default_connection: sf_dev
connections:
    sf_dev:
        type: snowflake
        authenticator: username_password
        account: my_dev_account
        warehouse: my_warehouse
        user: my_user
        password: ${SNOWFLAKE_PASSWORD}
    sf_prod:
        type: snowflake
        authenticator: username_password
        account: my_prod_account
        warehouse: my_warehouse
        user: my_user
        password: ${SNOWFLAKE_PASSWORD}

Note that:

• When you define multiple connections, default_connection is required.
• Keep secrets out of source control by using environment variables (for example SNOWFLAKE_PASSWORD).

Programmatic

import os

from relationalai.config import create_config
from relationalai.semantics import Model

cfg = create_config(
    connections={
        "sf_dev": {
            "type": "snowflake",
            "authenticator": "username_password",
            "account": "my_dev_account",
            "warehouse": "my_warehouse",
            "user": "my_user",
            "password": os.environ["SNOWFLAKE_PASSWORD"],
        },
        "sf_prod": {
            "type": "snowflake",
            "authenticator": "username_password",
            "account": "my_prod_account",
            "warehouse": "my_warehouse",
            "user": "my_user",
            "password": os.environ["SNOWFLAKE_PASSWORD"],
        },
    },
    default_connection="sf_dev",
)

# Use the config
m = Model("MyModel", config=cfg)

Note that:

• Use os.environ["..."] to fail fast when an environment variable is missing.
• To switch defaults, change default_connection or create a different config per environment.

Get the connection by creating a session

Create a Snowpark session from your configured Snowflake connection. Session creation exercises authentication, so it’s a good way to validate your config and fail fast on issues like missing or invalid credentials. It’s also a common starting point for running Snowpark operations in Python.

For more on using a Snowpark session, see Snowflake’s Session documentation.

Create a session from your default connection

Use the .get_session() method on Model.config to create a session from your default connection:

from relationalai.semantics import Model

m = Model("MyModel")
session = m.config.get_session()

# Execute a simple query to verify the session works:
session.sql("SELECT 1").collect()

Note that:

• get_session() uses default_connection when it is set.
• If you have exactly one connection, PyRel selects it as the default automatically.

Create a session from a specific connection

Use the .get_connection() method to get a specific connection by name, then call .get_session() on that connection:

from relationalai.semantics import Model

m = Model("MyModel")
conn = m.config.get_connection(name="<connection_name>")
session = conn.get_session()

# Execute a simple query to verify the session works:
session.sql("SELECT 1").collect()

Clear the session cache to create a fresh session

PyRel caches the Snowpark session it creates for a connection. Clear the cache when you rotate credentials or want to force a reconnect.

Call .clear_session_cache() on the connection to clear the cached session:

from relationalai.semantics import Model

m = Model("MyModel")
conn = m.config.get_default_connection()
conn.clear_session_cache()

Note that:

• The next get_session() call creates a new Snowpark session.
• You can also restart your Python process to clear the session cache.

Related resources:

• How database sessions are managed