Using programmatic access tokens for authentication¶

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

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

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

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');

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

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

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

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

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
)

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.

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>"

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"}'

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.

Listing programmatic access tokens¶

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

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;

Renaming a programmatic access token¶

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

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.

ALTER USER IF EXISTS example_user ROTATE PROGRAMMATIC ACCESS TOKEN example_token;

ALTER USER IF EXISTS example_user
  ROTATE PROGRAMMATIC ACCESS TOKEN example_token
  EXPIRE_ROTATED_TOKEN_AFTER_HOURS = 0;

+---------------+-----------------+-------------------------------------+
| token_name    | token_secret    | rotated_token_name                  |
|---------------+-----------------+-------------------------------------|
| EXAMPLE_TOKEN | ... (token) ... | EXAMPLE_TOKEN_ROTATED_1744239049066 |
+---------------+-----------------+-------------------------------------+

Revoking a programmatic access token¶

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

ALTER USER IF EXISTS example_user REMOVE PROGRAMMATIC ACCESS TOKEN example_token;