Authenticating Snowflake REST APIs with Snowflake (original) (raw)

This topic describes how to authenticate to the server when using the Snowflake REST APIs.

When you send a request, the request must include authentication information using either of the following:

Using key pair authentication

When using key pair authentication, you need to complete the following tasks:

  1. Set up key pair authentication
  2. Generate a JWT token

Set up key pair authentication

To use key pair authentication, follow these steps:

  1. Set up key pair authentication.
    As part of this process, you must:
    1. Generate a public-private key pair. The generated private key should be in a file (e.g. named rsa_key.p8).
    2. Assign the public key to your Snowflake user. After you assign the key to the user, run theDESCRIBE USER command. In the output, the RSA_PUBLIC_KEY_FP property should be set to the fingerprint of the public key assigned to the user.
      For instructions on how to generate the key pair and assign a key to a user, see Key-pair authentication and key-pair rotation.
  2. Use Snowflake CLI to verify that you can use the generated private key toconnect to Snowflake:
    $ snow connection test --account --user --private-key-path /rsa_key.p8
    If you generated an encrypted private key, Snowflake CLI prompts you for the passphrase that you created when you generated the key.

Generate a JWT token

To generate a JWT token in your application code, use the following steps:

  1. Generate the fingerprint (a SHA-256 hash) of the public key for the user. Prefix the fingerprint with SHA256:.

    For example:

    SHA256:_hash_

    You can also execute the SQL DESCRIBE USER command to get the value from the RSA_PUBLIC_KEY_FP property.

  2. Generate a JSON Web Token (JWT) with the following fields in the payload:
    Field Description Example
    iss Issuer of the JWT. Set it to the following value: account_identifier.user.SHA256:public_key_fingerprint where: account_identifier is your Snowflake account identifier. If you are using the account locator, exclude any region information from the account locator. user is your Snowflake user name. SHA256:public_key_fingerprint is the fingerprint that you generated in the previous step. Note The account_identifier and user values must use all uppercase characters. MYORGANIZATION-MYACCOUNT.MYUSER.SHA256:public_key_fingerprint
    sub Subject for the JWT. Set it to the following value: account_identifier.user MYORGANIZATION-MYACCOUNT.MYUSER
    iat Issue time for the JWT in UTC. Set the value to the current time value as either seconds or milliseconds. 1615370644 (seconds) . 1615370644000 (milliseconds)
    exp Expiration time for the JWT in UTC. You can specify the value as either seconds or milliseconds. Note The JWT is valid for at most one hour after the token is issued, even if you specify a longer expiration time. 1615374184 (seconds) . 1615374184000 (milliseconds)
  3. In each API request that you send, set the following headers:
    • Authorization: Bearer _JWT_
      where _JWT_ is the token that you generated.
    • (Optional) X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT
      If you omit the X-Snowflake-Authorization-Token-Type header, Snowflake determines the token type by examining the token.
      Even though this header is optional, you can choose to specify this header. You can set the header to one of the following values:
      * KEYPAIR_JWT (for key-pair authentication)
    * `OAUTH` (for OAuth)  
    * `PROGRAMMATIC_ACCESS_TOKEN` (for [programmatic access tokens](../../user-guide/programmatic-access-tokens))

Using OAuth

To use OAuth, follow these steps:

  1. Set up OAuth for authentication.
    See Introduction to OAuth for details on how to set up OAuth and get an OAuth token.
  2. Use Snowflake CLI to verify that you can use a generated OAuth token to connect to Snowflake:
    • For Linux and MacOS systems

      $ snow connection test --account --user --authenticator=oauth --token=

    • For Windows systems

      $ snow connection test --account --user --authenticator=oauth --token=""

  3. In each API request you send, set the following headers:
    • Authorization: Bearer _oauthtoken_
      where _oauthtoken_ is the generated OAuth token.
    • (Optional) X-Snowflake-Authorization-Token-Type: OAUTH
      If you omit the X-Snowflake-Authorization-Token-Type header, Snowflake determines the token type by examining the token.
      Even though this header is optional, you can choose to specify this header. You can set the header to one of the following values:
      * KEYPAIR_JWT (for key-pair authentication)
      * OAUTH (for OAuth)
      * PROGRAMMATIC_ACCESS_TOKEN (for programmatic access tokens)

Using a programmatic access token (PAT)

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

For example, if you are using cURL to send a request to aSnowflake REST API endpoint:

curl --location 'https://myorganization-myaccount.snowflakecomputing.com/api/v2/databases'
--header "Authorization: Bearer "

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

For more information, see Using a programmatic access token to authenticate to an endpoint.