Using programmatic access tokens for authentication

To authenticate to the following Snowflake endpoints, you can use a programmatic access token:

Note

Using programmatic access tokens to authenticate to Snowpark Container Services endpoints is not yet supported.

You can also use a programmatic access token as a replacement for a password in the following:

You can generate programmatic access tokens for human users (users with TYPE=PERSON) as well as service users (users with TYPE=SERVICE).

Prerequisites

You must fulfill the following prerequisites to generate and use programmatic access tokens:

Network policy requirements

By default, the user must be subject to a network policy with one or more network rules to generate or use programmatic access tokens:

  • For service users (where TYPE=SERVICE for the user), you can only generate or use a token if the user is subject to a network policy.

    This prerequisite limits the use of the token to requests from a specific set of addresses or network identifiers.

  • For human users (where TYPE=PERSON for the user), you can generate a token if the user is not subject to a network policy, but the user must be subject to a network policy to authenticate with this token.

    Users can bypass this when generating the token, but we don’t recommend this.

The network policy can be activated for all users in the account or for a specific user.

To change this requirement, create or modify an authentication policy that specifies a programmatic access token policy.

Execute the CREATE AUTHENTICATION POLICY or ALTER AUTHENTICATION POLICY command. In the PAT_POLICY clause, set NETWORK_POLICY_EVALUATION to one of the following values:

ENFORCED_REQUIRED (default behavior)

The user must be subject to a network policy to generate and use programmatic access tokens.

If the user is subject to a network policy, the network policy is enforced during authentication.

ENFORCED_NOT_REQUIRED

The user does not need to be subject to a network policy to generate and use programmatic access tokens.

If the user is subject to a network policy, the network policy is enforced during authentication.

NOT_ENFORCED

The user does not need to be subject to a network policy to generate and use programmatic access tokens.

If the user is subject to a network policy, the network policy is not enforced during authentication.

For example, to create an authentication policy that removes the network policy requirement but enforces any network policy that the user is subject to:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED
  );
Copy

Then, apply the authentication policy to an account or user.

As another example, to alter an existing authentication policy to remove the network policy requirement and prevent the enforcement of any network policy that the user is subject to:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    NETWORK_POLICY_EVALUATION = NOT_ENFORCED
  );
Copy

Authentication policy requirements

If there is an authentication policy that limits the authentication methods for a user, the user cannot generate and use programmatic access tokens unless the AUTHENTICATION_METHODS list in that policy includes 'PROGRAMMATIC_ACCESS_TOKEN'.

For example, suppose that an authentication policy limits users to using the OAuth and password methods to authenticate:

CREATE AUTHENTICATION POLICY my_auth_policy
  ...
  AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD')
  ...
Copy

Users can’t generate and use programmatic access tokens unless you add 'PROGRAMMATIC_ACCESS_TOKEN' to the AUTHENTICATION_METHODS list. You can use the ALTER AUTHENTICATION POLICY command to update this list.

For example:

ALTER AUTHENTICATION POLICY my_auth_policy
  SET AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD', 'PROGRAMMATIC_ACCESS_TOKEN');
Copy

Configuring the default and maximum expiration time

Administrators (users with the ACCOUNTADMIN role) can configure the following settings that affect the expiration time of programmatic access tokens:

Setting the maximum expiration time

By default, you can specify an expiration time up to 365 days for a token. If you want to reduce this to a shorter time, create or modify an authentication policy that specifies a programmatic access token policy with a maximum expiration time.

Execute the CREATE AUTHENTICATION POLICY or ALTER AUTHENTICATION POLICY command. In the PAT_POLICY clause, set MAX_EXPIRY_IN_DAYS to a value ranging from 1 to 365.

For example, to create an authentication policy that sets the maximum to 100 days:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    MAX_EXPIRY_IN_DAYS=100
  );
Copy

Then, apply the authentication policy to an account or user.

As another example, to alter an existing authentication policy to set the maximum to 90 days:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    MAX_EXPIRY_IN_DAYS=90
  );
Copy

Note

If there are existing programmatic access tokens with expiration times that exceed the new maximum expiration time, attempts to authenticate with those tokens will fail.

For example, suppose that you generate a programmatic access token named my_token with the expiration time of 7 days. If you later change the maximum expiration time for all tokens to 2 days, authenticating with my_token will fail because the expiration time of the token exceeds the new maximum expiration time.

Setting the default expiration time

By default, a programmatic access token expires after 15 days. If you want to change this, create or modify an authentication policy that specifies a programmatic access token policy with a default expiration.

Execute the CREATE AUTHENTICATION POLICY or ALTER AUTHENTICATION POLICY command. In the PAT_POLICY clause, set DEFAULT_EXPIRY_IN_DAYS to a value ranging from 1 to the maximum expiration time.

For example, to create an authentication policy that sets the default to 5 days:

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    DEFAULT_EXPIRY_IN_DAYS=5
  );
Copy

Then, apply the authentication policy to an account or user.

As another example, to alter an existing authentication policy to set the default to 30 days:

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    DEFAULT_EXPIRY_IN_DAYS=30
  );
Copy

Privileges required for programmatic access tokens

If you’re generating, modifying, dropping, or displaying a programmatic access token for yourself, you don’t need any special privileges.

If you’re generating, modifying, dropping, or displaying a programmatic access token for a different user (for example, for a service user), you must use a role that has the OWNERSHIP or MODIFY PROGRAMMATIC AUTHENTICATION METHODS privilege on that user.

For example, suppose that you want to grant users with the my_service_owner_role custom role the ability to generate and manage programmatic access tokens for the service user my_service_user. You can grant the MODIFY PROGRAMMATIC AUTHENTICATION METHODS privilege on the my_service_user user to the role my_service_owner_role:

GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER my_service_user
  TO ROLE my_service_owner_role;
Copy

Generating a programmatic access token

You can generate a programmatic access token in Snowsight or by executing SQL commands.

  1. Sign in to Snowsight.

  2. Select Admin » Users & Roles.

  3. Select the user that you want to generate the programmatic access token for.

  4. Under Programmatic access tokens, select Generate new token.

  5. In the New programmatic access token dialog, enter the following information:

    1. In the Name field, enter a name for the token.

      In the name, you can only use letters, numbers, and underscores. The name must start with a letter or underscore. Letters in the name are stored and resolved as uppercase characters.

    2. In the Comment field, enter a descriptive comment about the token.

      After you create the token, this comment is displayed under the token in the Programmatic access tokens section.

    3. From Expires in, choose the number of days after which the token should expire.

    4. If you’re generating the token on behalf of a user for a service (if the USER object has TYPE=SERVICE), or if you want to restrict the scope of the operations that can be performed, select One specific role (recommended), and select the role that should be used for privilege evaluation and object creation.

      When you use this token for authentication, any objects that you create are owned by this role, and this role is used for privilege evaluation.

      Note

      Secondary roles are not used, even if DEFAULT_SECONDARY_ROLES is set to (‘ALL’) for the user.

      If you select Any of my roles instead, any objects that you create owned by your primary role, and privileges are evaluated against your active roles.

    5. Select Generate.

  6. Copy or download the generated programmatic access token so that you can use the token for authentication.

    Note

    After you close this message box, you will not be able to copy or download this token.

The new token is listed in the Programmatic access tokens section.

As noted earlier, to use a programmatic access token, the user associated with the token must be subject to a network policy, unless you set up an authentication policy to change this requirement.

For human users (where the TYPE property of the user is PERSON), you can bypass this requirement temporarily by selecting More options » Bypass requirement for network policy.

After you create a programmatic access token, you cannot change the expiration date. You must revoke the token and generate a new token with the new expiration time.

If you specified a role for the programmatic access token and that role is revoked from the user, the programmatic access token uses the system PUBLIC role.

Using a programmatic access token

The following sections explain how to use a programmatic access token as a password and for authentication to a Snowflake endpoint:

Using a programmatic access token as a password

To authenticate with a programmatic access token as the password, you can specify the token for the value of the password in the driver settings or in the call to connect to Snowflake.

For example, if you’re using the Snowflake Connector for Python, you can specify the programmatic access token as the password argument when calling the snowflake.connector.connect method.

conn = snowflake.connector.connect(
    user=USER,
    password=<programmatic_access_token>,
    account=ACCOUNT,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
)
Copy

In the same way, you can use programmatic access tokens in place of a password in third-party applications (such as Tableau or PowerBI). Paste the programmatic access token in the field for the password.

Note

By default, using programmatic access tokens requires a network policy to be activated for a user or for all users in the account. To use programmatic access tokens with a third-party application, you must create a network policy that allows requests from the IP address ranges of the third-party application.

Using a programmatic access token to authenticate to an endpoint

To authenticate with a programmatic access token, set the following HTTP headers in the request:

  • Authorization: Bearer token_secret

  • X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN (optional)

For example, if you’re using cURL to send a request to a Snowflake REST API endpoint:

curl --location 'https://myorganization-myaccount.snowflakecomputing.com/api/v2/databases' \
  --header "Authorization: Bearer <token_secret>"
Copy

As another example, if you’re using cURL to send a request to the Snowflake SQL API endpoint:

curl -si -X POST https://myorganization-myaccount.snowflakecomputing.com/api/v2/statements \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"
  --header "Authorization: Bearer <token_secret>" \
  --data '{"statement": "select 1"}'
Copy

If the request fails with a PAT_INVALID error, the error might have occurred for one of the following reasons:

  • The user associated with the programmatic access token was not found.

  • Validation failed.

  • The role associated with the programmatic access token was not found.

  • The user is not associated with the specified programmatic access token.

Managing programmatic access tokens

The following sections explain how to use, modify, list, rotate, and revoke programmatic access tokens:

Listing programmatic access tokens

You can list the programmatic access token for a user in Snowsight or by executing SQL commands.

  1. Sign in to Snowsight.

  2. Select Admin » Users & Roles.

  3. Select the user who owns the programmatic access token.

    The programmatic access tokens for the user are listed Under Programmatic access tokens.

Renaming a programmatic access token

You can change the name of a programmatic access token in Snowsight or by executing SQL commands.

  1. Sign in to Snowsight.

  2. Select Admin » Users & Roles.

  3. Select the user associated with the programmatic access token.

  4. Under Programmatic access tokens, locate the programmatic access token and select More options » Edit.

  5. In the Name field, change the name of the token, and select Save.

Rotating a programmatic access token

You can rotate a programmatic access token in Snowsight or by executing SQL commands.

Rotating a token returns a new token secret that has the same name and an extended expiration time. Rotating a token also expires the existing token secret. Use the new token for authenticating to Snowflake.

  1. Sign in to Snowsight.

  2. Select Admin » Users & Roles.

  3. Select the user associated with the programmatic access token.

  4. Under Programmatic access tokens, locate the programmatic access token and select More options » Rotate.

  5. If you want the previous token secret to expire immediately, select Epxire current secret immediately.

  6. Select Rotate token.

  7. Copy or download the generated programmatic access token so that you can use the token for authentication.

    Note

    After you close this message box, you will not be able to copy or download this token.

Revoking a programmatic access token

You can revoke a programmatic access token in Snowsight or by executing SQL commands.

  1. Sign in to Snowsight.

  2. Select Admin » Users & Roles.

  3. Select the user associated with the programmatic access token.

  4. Under Programmatic access tokens, locate the programmatic access token and select More options » Delete.

Re-enabling a disabled programmatic access token

When you disable login access for a user or Snowflake locks out a user from logging in, the programmatic access tokens for that user are automatically disabled.

Note

Programmatic access tokens are not disabled when a user is temporarily locked out (for example, due to five or more failed attempts to authenticate).

If you run the SHOW USER PROGRAMMATIC ACCESS TOKENS command, the value in the status column is DISABLED for tokens associated with that user.

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;
Copy
+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+
| name          | user_name    | role_restriction | expires_at                    | status   | comment | created_on                    | created_by   | mins_to_bypass_network_policy_requirement | rotated_to |
|---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------|
| EXAMPLE_TOKEN | EXAMPLE_USER | MY_ROLE          | 2025-04-28 12:13:46.431 -0700 | DISABLED | NULL    | 2025-04-13 12:13:46.431 -0700 | EXAMPLE_USER | NULL                                      | NULL       |
+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+

If you later enable login access for that user or Snowflake unlocks login access for that user, the programmatic access tokens for that user remain disabled. To enable the tokens again, execute the ALTER USER … MODIFY PROGRAMMATIC ACCESS TOKEN (PAT) command, and set DISABLED to FALSE. For example:

ALTER USER example_user MODIFY PROGRAMMATIC ACCESS TOKEN example_token SET DISABLED = FALSE;
Copy

Best practices

  • If you need to store a programmatic access token, do so securely (for example, by using a password or secrets manager).

  • Avoid exposing programmatic access tokens in code.

  • Restrict the use of the token to a specific role when generating the token.

  • Regularly review and rotate programmatic access tokens. Users can set the expiration time when generating the token, and administrators can reduce the maximum expiration time for all tokens to encourage the rotation of tokens.

Limitations

  • You can only restrict a programmatic access token to a role when you generate the token. After you generate the token, you cannot change or remove the role that it’s restricted to.

  • You can only set the expiration time for a programmatic access token when you generate the token. After you generate the token, you cannot change the expiration time. You can revoke a programmatic access token and generate a new token with a different expiration time.

  • You can only view the secret for a programmatic access token when you create it. After you create a programmatic access token, you can only view information about the token and not the secret for the token.

  • Administrators can list all programmatic access tokens for a given user, but they cannot list all programmatic access tokens for an account.

  • You cannot recover a programmatic access token after you revoke it.