Authenticating Snowflake REST APIs with Snowflake

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 the DESCRIBE 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 SnowSQL to verify that you can use the generated private key to connect to Snowflake:

    $ snowsql -a <account_identifier> -u <user> --private-key-path <path>/rsa_key.p8
    Copy

    If you generated an encrypted private key, SnowSQL 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) (link removed) 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.

    • X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT

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 SnowSQL to verify that you can use a generated OAuth token to connect to Snowflake:

    • For Linux and MacOS systems

    $ snowsql -a <account_identifier> -u <user> --authenticator=oauth --token=<oauth_token>
    Copy

    • For Windows systems

    $ snowsql -a <account_identifier> -u <user> --authenticator=oauth --token="<oauth_token>"
    Copy

  3. In each API request you send, set the following headers:

    • Authorization: Bearer oauth_token

      where oauth_token is the generated OAuth token.

    • X-Snowflake-Authorization-Token-Type: OAUTH

Language: English