authentication.md

Authentication

Cortex Training authenticates through a Snowflake Programmatic Access Token (PAT). This page walks you through three steps:

1. Create a PAT — required regardless of which configuration method you use
2. Create the database — one-time setup for the connection config
3. Configure the client — pick one of the methods below to supply your PAT

Step 1: Create a PAT

Heads-up: By default, Snowflake only accepts a PAT from a user covered by a network policy. If Snowsight shows Missing network policy on your new token, see Network policy requirement before you configure the client.

1. Log in to your Snowflake account at https://<your-account>.snowflakecomputing.com

2. Click your user icon (bottom left)

   

3. Click Settings

   

4. Select Authentication

   

5. Click Generate token

   

6. Give it a name (e.g., cortex-training), set an expiry, and click Generate

   

7. Copy the token value immediately — you cannot view it again

   

Step 2: Configure the Client

Once you have a PAT, pick one of the following methods to configure the client. We recommend connections.toml.

Option A: connections.toml (recommended)

This is Snowflake's standard configuration file, shared across all Snowflake tools. Create or edit ~/.snowflake/connections.toml:

[training]
account = "ORG-ACCOUNT"
host = "ACCOUNT.snowflakecomputing.com"
user = "YOUR_USERNAME"
authenticator = "programmatic_access_token"
token = "YOUR_PAT"
database = "CORTEX_TRAINING_DB"
schema = "PUBLIC"

Protect the file:

chmod 600 ~/.snowflake/connections.toml

Finding your account and host

• account: your org and account name joined by a hyphen, e.g., MYORG-MYACCOUNT. You can find this in your Snowsight URL: https://app.snowflake.com/MYORG/MYACCOUNT → MYORG-MYACCOUNT.
• host: ACCOUNT.snowflakecomputing.com, e.g., myorg-myaccount.snowflakecomputing.com. Snowsight may show an account name with an underscore (my_acct.…). Snowflake's certificates are wildcards (for example, *.snowflakecomputing.com), and a wildcard can't match a name containing _, so the client uses the hyphen form (my-acct.…) for its own HTTPS calls. Either form works in your profile.

Setting the default connection

To avoid passing --connection training on every command, set a default using any of these methods:

• Name the profile [default] instead of [training]
• Set the environment variable:

  export SNOWFLAKE_DEFAULT_CONNECTION_NAME=training

• Add default_connection_name = "training" to ~/.snowflake/config.toml

Verify

cortex-training capacity

This should print your available GPU capacity.

Cortex Training keeps your jobs and checkpoints in the profile's database, and it never creates that database for you. Create it once, in Snowsight:

CREATE DATABASE IF NOT EXISTS CORTEX_TRAINING_DB;

If a command can't find the database, it stops with an error that names your role and the database, and how to fix it: create it, ask an admin for GRANT USAGE, or use another database with --database.

Option B: JSON config (legacy)

Create a JSON file outside the repository:

{
  "host": "ACCOUNT.snowflakecomputing.com",
  "pat": "YOUR_PAT",
  "database": "CORTEX_TRAINING_DB",
  "schema": "PUBLIC"
}

Register it once so subsequent commands use it automatically:

cortex-training login ~/cortex-training-config.json
cortex-training capacity

Option C: Environment variables

Set credentials directly in your shell:

export CORTEX_TRAINING_HOST="ACCOUNT.snowflakecomputing.com"
export CORTEX_TRAINING_PAT="YOUR_PAT"
export CORTEX_TRAINING_DATABASE="CORTEX_TRAINING_DB"
export CORTEX_TRAINING_SCHEMA="PUBLIC"

Then run commands directly:

cortex-training capacity

Environment variables override both connections.toml and JSON config values. This is useful for CI/CD pipelines or when you don't want secrets in files.

Snowflake-prefixed variants (SNOWFLAKE_PAT, SNOWFLAKE_HOST, SNOWFLAKE_DATABASE, SNOWFLAKE_SCHEMA) are also accepted.

Troubleshooting

Error	Cause	Fix
SSL certificate verify failed	The host is not a snowflakecomputing.com address and has an underscore (for example, a custom name such as ml_team.example.com), or a company network tool that inspects HTTPS traffic replaces Snowflake's certificate with its own	Use the hyphen form (ml-team.example.com), or ask IT for the company certificate file and set REQUESTS_CA_BUNDLE=/path/to/company-ca.pem
Failed to resolve / NameResolutionError for a …privatelink.snowflakecomputing.com host with a - where your account name has a _	With PrivateLink, the client calls the hyphen form of your account host (see the host note above), and your private DNS may only have a record for the underscore form	Ask your network admin to add a DNS record for the hyphen form. SYSTEM$GET_PRIVATELINK_CONFIG() lists the hyphenated URLs (for example, privatelink-dashed-urls-for-duo)
no PAT found	Missing token in config	Add token to connections.toml, pat to JSON, or set CORTEX_TRAINING_PAT
401 Unauthorized	PAT expired, invalid, or your user has no network policy	See Network policy requirement, or regenerate the PAT
394400 (08001) / Programmatic access token is invalid	Your user has no network policy, or the PAT is wrong	See Network policy requirement

Network policy requirement

By default, Snowflake only accepts a PAT from a user covered by a network policy, a list of IP addresses allowed to sign in. You can create a PAT without one, but Snowflake then rejects it with Programmatic access token is invalid (or 401 Unauthorized). In Snowsight, the token shows Missing network policy under Settings → Authentication.

1. Confirm the cause (one minute)

1. In Snowsight, open Settings → Authentication.
2. On your token, open the ⋯ menu and choose Bypass requirement for network policy.
3. Run cortex-training capacity again.

If it now works, the network policy is the cause. The bypass is temporary, so continue with step 2.

2. Fix it permanently

An account administrator (ACCOUNTADMIN or SECURITYADMIN) picks one of these options:

Option	Best when	Trade-off
A. Network policy	You connect from fixed IP addresses (office, VPN, cloud VM)	Must be updated whenever your IP changes
B. Authentication policy	Your IP changes (home network, laptop on the go)	The PAT works from any IP, so keep it secret

Option A: allow your IP addresses with a network policy

USE ROLE ACCOUNTADMIN;

CREATE NETWORK POLICY CORTEX_TRAINING_ACCESS
  ALLOWED_IP_LIST = ('<cli-machine-ip>', '<snowsight-ip>');

ALTER USER <your-username> SET NETWORK_POLICY = CORTEX_TRAINING_ACCESS;

• <cli-machine-ip> is the public IP of the machine that runs cortex-training. Get it on that machine with curl -s https://ifconfig.me.
• <snowsight-ip> is the IP you open Snowsight from. Include it so the policy doesn't lock you out of Snowsight.

The policy pins you to those IP addresses, for Snowsight logins too. If your public IP changes, which is common on home networks without a VPN, logins fail again until an administrator updates the list from an IP that is still allowed:

ALTER NETWORK POLICY CORTEX_TRAINING_ACCESS
  SET ALLOWED_IP_LIST = ('<new-cli-machine-ip>', '<snowsight-ip>');

Option B: drop the network-policy requirement for PATs with an authentication policy

USE ROLE ACCOUNTADMIN;

CREATE DATABASE IF NOT EXISTS CORTEX_TRAINING_DB;

CREATE AUTHENTICATION POLICY CORTEX_TRAINING_DB.PUBLIC.CORTEX_TRAINING_PAT_POLICY
  PAT_POLICY = (NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED);

ALTER USER <your-username>
  SET AUTHENTICATION POLICY CORTEX_TRAINING_DB.PUBLIC.CORTEX_TRAINING_PAT_POLICY;

ENFORCED_NOT_REQUIRED means your user no longer needs a network policy to use a PAT, but any network policy that does apply is still enforced.

If your account or user already has an authentication policy (for example, one that requires MFA), don't create a new one: a user-level policy replaces the account-level policy for that user, which can drop those other settings. Add the PAT_POLICY setting to the existing policy instead. See Snowflake's programmatic access token documentation.

Still failing?

If Snowsight shows no network policy warning, or the bypass didn't help:

• Generate a new PAT and paste it without extra spaces or quotes.
• Check that user in your connection config is the user who owns the token.