The integrations API is a REST API that allows you to integrate your remote data platform with Immuta so that Immuta can manage and enforce access controls on your data.

Getting started guide

This task-based guide includes end-to-end instructions for implementing your integration - from authenticating with the API to mapping your users into Immuta so that they can access policy-enforced data. A basic request and payload example is provided for configuring each integration.

How-to guides

These guides provide step-by-step instructions for creating and managing your integration and include configuration setting examples that vary in complexity.

• Amazon S3 integration guide

• Azure Synapse Analytics integration guide

• Databricks Unity Catalog integration guide

• Google BigQuery integration guide

• Redshift integration guide

• Snowflake integration guide

• Starburst (Trino) integration guide

Reference guides

These guides define request and body parameters, response schema, and common error messages.

• Integrations API endpoints

• Integrations API payload

• Response schema

• HTTP status codes and error messages

The Amazon S3 resource allows you to create, configure, and manage your S3 integration. In this integration, Immuta provides coarse-grained access controls for data in S3 by performing permission grants using the Access Grants API so that users don't have to manage individual IAM policies themselves.

Use the /integrations endpoint to

• configure an S3 integration

• get an S3 integration

• get all integrations

• delete an S3 integration

• create an S3 data source

Requirements

• S3 integration enabled in Immuta; contact your Immuta representative to enable this integration

• No location is registered in your AWS Access Grants instance before configuring the integration in Immuta

Permissions

• APPLICATION_ADMIN Immuta permission to configure the integration

• CREATE_S3_DATASOURCE Immuta permission to register S3 data sources

• The AWS account credentials or optional AWS IAM role you provide Immuta when configuring the integration must

  • have ownership of the buckets Immuta will enforce policies on

  • have the following permissions to create locations and issue grants:

    • s3:CreateAccessGrant

    • s3:CreateAccessGrantsLocation

    • s3:DeleteAccessGrant

    • s3:DeleteAccessGrantsLocation

    • s3:GetAccessGrant

    • s3:GetAccessGrantsInstance

    • s3:GetAccessGrantsInstanceForPrefix

    • s3:GetAccessGrantsInstanceResourcePolicy

    • s3:GetAccessGrantsLocation

    • s3:ListAccessGrants

    • s3:ListAccessGrantsInstances

    • s3:ListAccessGrantsLocations

    • iam:PassRole

    • iam:GetRole

Set up S3 Access Grants instance

1. Follow AWS documentation to create an Access Grants instance using the S3 console, AWS CLI, AWS SDKs, or the REST API. AWS supports one Access Grants instance per region per AWS account.

2. Follow the instructions at the top of the "Register a location" page in AWS documentation to create an AWS IAM role and give the S3 Access Grants service principal access to this role in the resource policy file. You will add this role to your integration configuration in Immuta so that Immuta can register this role with your Access Grants location. The AWS documentation linked above gives a complete policy example, but your policy should include the following permissions:

   • sts:AssumeRole

   • sts:SetSourceIdentity

   • sts:SetContext

3. Follow the instructions at the top of the "Register a location" page in AWS documentation to create an IAM policy with the following permissions, and attach the policy to the IAM role you created to grant the permissions to the role. The AWS documentation linked above gives a complete example, but the policy should at least include the following permissions:

   • s3:GetObject

   • s3:GetObjectVersion

   • s3:GetObjectAcl

   • s3:GetObjectVersionAcl

   • s3:ListMultipartUploadParts

   • s3:PutObject

   • s3:PutObjectAcl

   • s3:PutObjectVersionAcl

   • s3:DeleteObject

   • s3:DeleteObjectVersion

   • s3:AbortMultipartUpload

   • s3:ListBucket

   • s3:ListAllMyBuckets

   • iam:passRole

   If you use server-side encryption with AWS Key Management Service (AWS KMS) keys to encrypt your data, the following permissions are required for the IAM role in the policy. If you do not use this feature, do not include these permissions in your IAM policy:

   • kms:Decrypt

   • kms:GenerateDataKey

4. Opt to create an AWS IAM role that Immuta can use to create Access Grants locations and issue grants. This role must have the S3 permissions listed in the permissions section.

Configure the integration in Immuta

AWS S3 access key example

This request configures the integration using the AWS access key authentication method.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Native S3",
    "autoBootstrap": false,
    "config": {
      "name": "S3 integration",
      "awsAccountId": "123456789",
      "awsRegion": "us-east-1",
      "awsLocationRole": "arn:aws:iam::123456789:role/access-grants-instance-role",
      "awsLocationPath": "s3://",
      "authenticationType": "accessKey",
      "awsAccessKeyId": "123456789",
      "awsSecretAccessKey": "123456789"
    }
    }'

1. Copy the request example. The example uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Change the config values to your own, where

   • name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.

   • awsAccountId is the ID of your AWS account.

   • awsRegion is the account's AWS region (such as us-east1).

   • awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.

   • awsLocationPath is the base S3 location prefix that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.

   • awsAccessKeyId is the AWS access key ID of the AWS account configuring the integration.

   • awsSecretAccessKey is the AWS secret access key of the AWS account configuring the integration.

AWS S3 automatic authentication example

This request configures the integration using the automatic authentication method, which searches and obtains credentials using the AWS SDK's default credential provider chain. This method requires a configured IAM role for a service account and is only supported if you're using a self-managed deployment of Immuta. Work with your Immuta representative to customize your deployment and set up an IAM role for a service account that can give Immuta the credentials to set up the integration.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Native S3",
    "autoBootstrap": false,
    "config": {
      "name": "S3 integration",
      "awsAccountId": "123456789",
      "awsRegion": "us-east-1",
      "awsLocationRole": "arn:aws:iam::123456789:role/access-grants-instance-role",
      "awsLocationPath": "s3://",
      "authenticationType": "auto"
    }
    }'

1. Copy the request example. The example uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Change the config values to your own, where

   • name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.

   • awsAccountId is the ID of your AWS account.

   • awsRegion is the account's AWS region (such as us-east1).

   • awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.

   • awsLocationPath is the base S3 location that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the S3 integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "There is no existing integration matching this configuration",
      "status": "passed"
    },
    {
      "name": "The provided integration name is unique across Immuta S3 integrations",
      "status": "passed"
    },
    {
      "name": "The provided access grants location role is a valid ARN format",
      "status": "passed"
    },
    {
      "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
      "status": "passed"
    },
    {
      "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
      "status": "passed"
    },
    {
      "name": "The provided S3 path exists and Immuta can list prefixes",
      "status": "passed"
    },
    {
      "name": "An AWS Access Grants location does not yet exist for the provided path",
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Access Grants location already exists on provided path."
}

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the GET /integrations endpoint.

Response

The response returns an S3 integration configuration. See the response schema reference for details about the response schema. An unsuccessful response returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "There is no existing integration matching this configuration",
        "status": "passed"
      },
      {
        "name": "The provided integration name is unique across Immuta S3 integrations",
        "status": "passed"
      },
      {
        "name": "The provided access grants location role is a valid ARN format",
        "status": "passed"
      },
      {
        "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
        "status": "passed"
      },
      {
        "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
        "status": "passed"
      },
      {
        "name": "The provided S3 path exists and Immuta can list prefixes",
        "status": "passed"
      },
      {
        "name": "An AWS Access Grants location does not yet exist for the provided path",
        "status": "passed"
      }
    ]
  },
  "type": "Native S3",
  "autoBootstrap": false,
  "config": {
    "port": 443,
    "name": "S3 integration",
    "awsAccountId": "123456789",
    "awsRegion": "us-east-1",
    "awsLocationRole": "arn:aws:iam::123456789:role/access-grants-instance-role",
    "awsLocationPath": "s3://",
    "authenticationType": "accessKey",
    "awsAccessKeyId": "123456789",
    "awsSecretAccessKey": "123456789"
  }
  }

Get all integrations

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

Response

The response returns the configuration for all integrations. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

[
  {
    "id": "1",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
      {
        "name": "Initial Validation: Basic Connection Test",
        "status": "passed"
      },
      {
        "name": "Initial Validation: Default Warehouse Access Test",
        "status": "passed",
        "result": []
      },
      {
        "name": "Initial Validation: Validate access to Privileged Role",
        "status": "passed",
        "result": []
      },
      {
        "name": "Validate Automatic: Database Does Not Exist",
        "status": "passed"
      },
      {
        "name": "Validate Automatic: Impersonation Role Does Not Exist",
        "status": "skipped"
      },
      {
        "name": "Validate Automatic Bootstrap User Grants",
        "status": "passed"
      }
    ] },
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "port": 443,
      "audit": {
        "enabled": false
        },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "lineage": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "<REDACTED>",
      "password": "<REDACTED>",
      "role": "ACCOUNTADMIN"
    }
    },
  {
    "id": "123456789",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "There is no existing integration matching this configuration",
          "status": "passed"
        },
        {
          "name": "The provided integration name is unique across Immuta S3 integrations",
          "status": "passed"
        },
        {
          "name": "The provided access grants location role is a valid ARN format",
          "status": "passed"
        },
        {
          "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
          "status": "passed"
        },
        {
          "name": "The provided S3 path exists and Immuta can list prefixes",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants location does not yet exist for the provided path",
          "status": "passed"
        }
      ] },
      "type": "Native S3",
      "autoBootstrap": false,
      "config": {
        "port": 443,
        "name": "S3 integration",
        "awsAccountId": "123456789",
        "awsRegion": "us-east-1",
        "awsLocationRole": "arn:aws:iam::123456789:role/access-grants-instance-role",
        "awsLocationPath": "s3://",
        "authenticationType": "accessKey",
        "awsAccessKeyId": "123456789",
        "awsSecretAccessKey": "123456789"
      }
  }
]

Delete an integration

curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

The response returns the status of the S3 integration configuration that has been deleted. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "id": "123456789",
  "status": "deleting",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "The provided access grants location role is a valid ARN format",
        "status": "passed"
      },
      {
        "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
        "status": "passed"
      },
      {
        "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
        "status": "passed"
      },
      {
        "name": "The provided S3 path exists and Immuta can list prefixes",
        "status": "passed"
      }
    ]
  }
}

Create a data source

curl -X 'POST' \
    'https://www.organization.immuta.com/native-s3/handler' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Native S3",
    "integrationId": 123456789,
    "dataSources": [
      {
        "dataSourceName": "Research Data",
        "prefix": "/research-data"
      }
    ]
    }'

1. Copy the request example. The example uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Change the integrationsID to the ID of your S3 integration. This ID can be retrieved with the GET /integrations request.

4. Change the dataSources values to your own, where

   • dataSourceName is the name of your data source.

   • prefix creates a data source for the prefix, bucket, or object provided in the path. If the data source prefix ends in a wildcard (), it protects all items starting with that prefix. If the data source prefix ends without a wildcard (), it protects a single object.

See the S3 data source payload description for parameter definitions and value types.

Response

The response returns the ID, name, and prefix of the data source. See the response schema reference for details about the response schema. An unsuccessful response returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

The Starburst (Trino) resource allows you to create and manage your Starburst (Trino) integration. In this integration, Immuta policies are translated into Starburst rules and permissions and applied directly to tables within users’ existing catalogs.

Use the /integrations endpoint to

Requirements

• APPLICATION_ADMIN Immuta permission

• A valid

Configure the integration

To configure the Starburst (Trino) integration, complete the following steps:

Generate the configuration snippet

1. Copy the request example. The example provided uses JSON format, but the request also accepts YAML.

Response

Configure the cluster

1. Navigate to the Immuta App Settings page and click the Integrations tab.

2. Click your enabled Starburst (Trino) integration and copy the configuration snippet displayed.

Get an integration

1. Copy the request example.

Response

Get all integrations

1. Copy the request example.

Response

Delete an integration

1. Copy the request example.

3. Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

In the Snowflake integration, Immuta manages access to Snowflake tables by administering Snowflake row access policies and column masking policies on those tables, allowing users to query tables directly in Snowflake while dynamic policies are enforced.

Use the /integrations endpoint to

• configure a Snowflake integration

• get a Snowflake integration

• get all integrations

• update a Snowflake integration

• delete a Snowflake integration

Requirements

• APPLICATION_ADMIN Immuta permission

• Snowflake Enterprise account

• Role used to configure, edit, or remove the integration needs to have the following Snowflake privileges:

  • CREATE DATABASE ON ACCOUNT WITH GRANT OPTION

  • CREATE ROLE ON ACCOUNT WITH GRANT OPTION

  • CREATE USER ON ACCOUNT WITH GRANT OPTION

  • MANAGE GRANTS ON ACCOUNT WITH GRANT OPTION

  • APPLY MASKING POLICY ON ACCOUNT WITH GRANT OPTION

  • APPLY ROW ACCESS POLICY ON ACCOUNT WITH GRANT OPTION

Configure the integration

You have two options for configuring your Snowflake integration:

• Automatic setup: Grant Immuta one-time use of credentials to automatically configure your Snowflake environment and the integration. When performing an automated installation, Immuta requires temporary, one-time use of credentials with the Snowflake privileges listed in the requirements section.

  These permissions will be used to create and configure a new Immuta-managed database within the specified Snowflake instance. The credentials are not stored or saved by Immuta, and Immuta doesn’t retain access to them after initial setup is complete.

  You can create a new account for Immuta to use that has these permissions, or you can grant temporary use of a pre-existing account. By default, the pre-existing account with appropriate permissions is ACCOUNTADMIN. If you create a new account, it can be deleted after initial setup is complete.

• Manual setup: Run the Immuta script in your Snowflake environment yourself to configure your Snowflake environment and the integration. The specified role used to run the bootstrap needs to have the Snowflake privileges listed in the requirements section.

Automatic setup

1. Select the section below that matches your authentication method.

2. Copy the request example and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

Username and password authentication example

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "authenticationType": "userPassword",
      "username": "taylor@snowflake.com",
      "password": "abc1234",
      "role": "ACCOUNTADMIN"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • username and password are credentials of a Snowflake account attached to a role with the privileges outlined above. These credentials are not stored; they are used by Immuta to configure the integration.

   • role is a Snowflake role that has been granted the privileges outlined above.

Snowflake key pair authentication example

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "authenticationType": "keyPair",
      "username": "SYSTEM_ACCOUNT",
      "privateKey": "-----BEGIN PRIVATE KEY-----\n<first line of private key content>\n<another line of private key content>\n<another line of private key content>\n-----END PRIVATE KEY-----"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.

   • privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: . If you are using another means of configuration, such as a Python script, the should not be added.

   • connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.

Response

The response returns the status of the Snowflake integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "status": "passed"
    },
    {
      "name": "Initial Validation: Default Warehouse Access Test",
      "status": "passed",
      "result": []
    },
    {
      "name": "Initial Validation: Validate access to Privileged Role",
      "status": "passed",
      "result": []
    },
    {
      "name": "Validate Automatic: Database Does Not Exist",
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Impersonation Role Does Not Exist",
      "status": "skipped"
    },
    {
      "name": "Validate Automatic Bootstrap User Grants",
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Snowflake integration already exists on host organization.us-east-1.snowflakecomputing.com (id = 123456789)"
}

Manual setup

To manually configure the integration, complete the following steps:

1. Generate the Immuta script and run it in your Snowflake environment.

2. Configure the integration in Immuta.

Generate the script

1. Select the section below that matches your authentication method.

2. Copy the request example and replace the values with your own as directed to generate the script. The examples provided use JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

Username and password authentication example

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": false,
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "taylor@snowflake.com",
      "password": "abc1234"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.

3. Run the script returned in the response in your Snowflake environment.

Snowflake key pair authentication example

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": false,
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "keyPair",
      "username": "SYSTEM_ACCOUNT",
      "privateKey": "-----BEGIN PRIVATE KEY-----\n<first line of private key content>\n<another line of private key content>\n<another line of private key content>\n-----END PRIVATE KEY-----"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.

   • privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: . If you are using another means of configuration, such as a Python script, the should not be added.

   • connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.

3. Run the script returned in the response in your Snowflake environment.

Snowflake External OAuth authentication example

In this example, Snowflake External OAuth is used to authenticate the system account user, ensuring secure communication between Immuta and Snowflake. To use this authentication method, autoBootstrap must be false.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "impersonation": {
        "enabled": true,
        "role": "IMMUTA_IMPERSONATION"
      },
      "audit": {
        "enabled": false
      },
      "workspaces": {
        "enabled": true,
        "warehouses": ["SAMPLE_WAREHOUSE"]
      },
      "authenticationType": "oAuthClientCredentials",
      "oAuthClientConfig": {
        "provider": "Okta",
        "clientId": "123456abc",
        "useCertificate": false,
        "clientSecret": "secret",
        "authorityUrl": "example.authority.com"
      }
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces.enabled specifies whether Immuta project workspaces are enabled for Snowflake.

   • workspaces.warehouses is a list of warehouses that workspace users have usage privileges on.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username is the system account user that can act on Snowflake objects and configure the integration.

   • oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.

3. Run the script returned in the response in your Snowflake environment.

Response

The response returns the script for you to run in your environment.

Configure the integration in Immuta

1. Select the section below that matches your authentication method.

2. Copy the request example and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML. The parameters and values you provide in this payload must match those you provided when generating the script.

See the config object description for parameter definitions, value types, and additional configuration options.

Username and password authentication example

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": false,
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "taylor@snowflake.com",
      "password": "abc1234"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the script, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.

Snowflake key pair authentication example

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": false,
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "keyPair",
      "username": "SYSTEM_ACCOUNT",
      "privateKey": "-----BEGIN PRIVATE KEY-----\n<first line of private key content>\n<another line of private key content>\n<another line of private key content>\n-----END PRIVATE KEY-----"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the script, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.

   • privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: . If you are using another means of configuration, such as a Python script, the should not be added.

   • connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.

Snowflake External OAuth authentication example

In this example, Snowflake External OAuth is used to authenticate the system account user, ensuring secure communication between Immuta and Snowflake. To use this authentication method, autoBootstrap must be false.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "impersonation": {
        "enabled": true,
        "role": "IMMUTA_IMPERSONATION"
      },
      "workspaces": {
        "enabled": true,
        "warehouses": ["SAMPLE_WAREHOUSE"]
      },
      "authenticationType": "oAuthClientCredentials",
      "oAuthClientConfig": {
        "provider": "Okta",
        "clientId": "123456abc",
        "useCertificate": false,
        "clientSecret": "secret",
        "authorityUrl": "example.authority.com"
      }
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the script, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • workspaces specifies whether Immuta project workspaces are enabled for Snowflake. See the object description for details about child parameters.

   • oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.

Response

The response returns the status of the Snowflake integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "status": "passed"
    },
    {
      "name": "Initial Validation: Default Warehouse Access Test",
      "status": "passed",
      "result": []
    },
    {
      "name": "Initial Validation: Validate access to Privileged Role",
      "status": "passed",
      "result": []
    },
    {
      "name": "Validate Automatic: Database Does Not Exist",
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Impersonation Role Does Not Exist",
      "status": "skipped"
    },
    {
      "name": "Validate Automatic Bootstrap User Grants",
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Snowflake integration already exists on host organization.us-east-1.snowflakecomputing.com (id = 123456789)"
}

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the GET /integrations endpoint.

Response

The response returns the Snowflake integration configuration. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "status": "passed"
    },
    {
      "name": "Initial Validation: Default Warehouse Access Test",
      "status": "passed",
      "result": []
    },
    {
      "name": "Initial Validation: Validate access to Privileged Role",
      "status": "passed",
      "result": []
    },
    {
      "name": "Validate Automatic: Database Does Not Exist",
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Impersonation Role Does Not Exist",
      "status": "skipped"
    },
    {
      "name": "Validate Automatic Bootstrap User Grants",
      "status": "passed"
    }
    ]
  },
  "type": "Snowflake",
  "autoBootstrap": true,
  "config": {
    "host": "organization.us-east-1.snowflakecomputing.com",
    "warehouse": "SAMPLE_WAREHOUSE",
    "database": "SNOWFLAKE_SAMPLE_DATA",
    "port": 443,
    "audit": {
      "enabled": false,
      },
    "workspaces": {
      "enabled": false
    },
    "impersonation": {
      "enabled": false
    },
    "lineage": {
      "enabled": false
    },
    "authenticationType": "userPassword",
    "username": "<REDACTED>",
    "password": "<REDACTED>",
    "role": "ACCOUNTADMIN"
  }
}

{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "status": "passed"
    },
    {
      "name": "Initial Validation: Default Warehouse Access Test",
      "status": "passed",
      "result": []
    },
    {
      "name": "Initial Validation: Validate access to Privileged Role",
      "status": "passed",
      "result": []
    },
    {
      "name": "Validate Automatic: Database Does Not Exist",
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Impersonation Role Does Not Exist",
      "status": "skipped"
    },
    {
      "name": "Validate Automatic Bootstrap User Grants",
      "status": "passed"
    }
    ]
  },
  "type": "Snowflake",
  "autoBootstrap": false,
  "config": {
    "host": "organization.us-east-1.snowflakecomputing.com",
    "warehouse": "SAMPLE_WAREHOUSE",
    "database": "SNOWFLAKE_SAMPLE_DATA",
    "port": 443,
    "impersonation": {
      "enabled": true,
      "role": "IMMUTA_IMPERSONATION"
    },
    "audit": {
      "enabled": false
    },
    "workspaces": {
      "enabled": true,
      "warehouses": ["SAMPLE_WAREHOUSE"]
    },
    "lineage": {
      "enabled": false
    },
    "authenticationType": "oAuthClientCredentials",
    "oAuthClientConfig": {
      "provider": "Okta",
      "clientId": "123456abc",
      "useCertificate": false,
      "clientSecret": "secret",
      "authorityUrl": "example.authority.com"
    }
  }
}

Get all integrations

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Response

The response returns the configuration for all integrations. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

[
  {
    "id": "1",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
      {
        "name": "Initial Validation: Basic Connection Test",
        "status": "passed"
      },
      {
        "name": "Initial Validation: Default Warehouse Access Test",
        "status": "passed",
        "result": []
      },
      {
        "name": "Initial Validation: Validate access to Privileged Role",
        "status": "passed",
        "result": []
      },
      {
        "name": "Validate Automatic: Database Does Not Exist",
        "status": "passed"
      },
      {
        "name": "Validate Automatic: Impersonation Role Does Not Exist",
        "status": "skipped"
      },
      {
        "name": "Validate Automatic Bootstrap User Grants",
        "status": "passed"
      }
    ] },
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "port": 443,
      "audit": {
          "enabled": false
        },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "lineage": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "<REDACTED>",
      "password": "<REDACTED>",
      "role": "ACCOUNTADMIN"
    },
    {
      "id": "2",
      "status": "enabled",
      "type": "Databricks",
      "validationResults": {
        "status": "passed",
        "validationTests": [
        {
          "name": "Metastore validation",
          "status": "passed"
        },
        {
          "name": "Basic Connection Test",
          "result": [
          {
            "1": 1
          }
          ],
          "status": "passed"
        }
        ]
      },
      "autoBootstrap": true,
      "config": {
        "workspaceUrl": "www.example-workspace.cloud.databricks.com",
        "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
        "token": "REDACTED",
        "audit": {
          "enabled": false
        },
        "catalog": "immuta"
      }
    }
  }
]

Update an integration configuration

You have two options for updating your integration. Follow the steps that match your initial configuration of autoBootstrap:

• automatic update (autoBootstrap is true)

• manual update (autoBootstrap is false)

Automatic update

1. Select the section below that matches your authentication method.

2. Copy the request example and replace the values with your own as directed to update the integration settings. The examples provided use JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

Username and password authentication example

This request updates the configuration to enable query audit in Snowflake.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": true
      },
      "authenticationType": "userPassword",
      "username": "taylor@snowflake.com",
      "password": "abc1234",
      "role": "ACCOUNTADMIN"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • username and password are credentials of a Snowflake account attached to a role with the privileges outlined above. These credentials are not stored; they are used by Immuta to enable or disable configuration settings.

   • role is a Snowflake role that has been granted the privileges outlined above.

Snowflake key pair authentication example

This request updates the configuration to enable query audit in Snowflake.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": true
      },
      "authenticationType": "keyPair",
      "username": "SYSTEM_ACCOUNT",
      "privateKey": "-----BEGIN PRIVATE KEY-----\n<first line of private key content>\n<another line of private key content>\n<another line of private key content>\n-----END PRIVATE KEY-----"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.

   • privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: . If you are using another means of configuration, such as a Python script, the should not be added.

   • connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.

Response

The response returns the status of the Snowflake integration configuration. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "status": "passed"
    },
    {
      "name": "Initial Validation: Default Warehouse Access Test",
      "status": "passed",
      "result": []
    },
    {
      "name": "Initial Validation: Validate access to Privileged Role",
      "status": "passed",
      "result": []
    },
    {
      "name": "Validate Automatic: Database Does Not Exist",
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Impersonation Role Does Not Exist",
      "status": "skipped"
    },
    {
      "name": "Validate Automatic Bootstrap User Grants",
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Unable to edit integration with ID 123456789 in current state editing."
}

Manual update

To manually update the integration, complete the following steps:

1. Generate the updated Immuta script and run it in your Snowflake environment.

2. Update the integration in Immuta.

Generate the updated script

1. Select the section below that matches your authentication method.

2. Copy the request example and replace the values with your own as directed to generate the script. The examples provided use JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

Username and password authentication example"

This request updates the configuration to enable query audit in Snowflake.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/{id}/scripts/edit' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": true
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "taylor@snowflake.com",
      "password": "abc1234"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.

4. Run the script returned in the response in your Snowflake environment.

Snowflake key pair authentication example

This request updates the configuration to enable query audit in Snowflake.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/{id}/scripts/edit' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": true
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "keyPair",
      "username": "SYSTEM_ACCOUNT",
      "privateKey": "-----BEGIN PRIVATE KEY-----\n<first line of private key content>\n<another line of private key content>\n<another line of private key content>\n-----END PRIVATE KEY-----"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.

   • privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: . If you are using another means of configuration, such as a Python script, the should not be added.

   • connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.

4. Run the script returned in the response in your Snowflake environment.

Snowflake External OAuth authentication example

This request updates the configuration to disable Snowflake workspaces for the integration.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/{id}/scripts/edit' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "impersonation": {
        "enabled": true,
        "role": "IMMUTA_IMPERSONATION"
      },
      "audit": {
        "enabled": true
      },
      "workspaces": {
        "enabled": false
      },
      "authenticationType": "oAuthClientCredentials",
      "oAuthClientConfig": {
        "provider": "Okta",
        "clientId": "123456abc",
        "useCertificate": false,
        "clientSecret": "secret",
        "authorityUrl": "example.authority.com"
      }
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username is the system account user that can act on Snowflake objects and configure the integration.

   • oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.

4. Run the script returned in the response in your Snowflake environment.

Response

The response returns the script for you to run in your environment.

Update the integration in Immuta

1. Select the section below that matches your authentication method.

2. Copy the request example and replace the values with your own as directed to update the integration settings. The examples provided use JSON format, but the request also accepts YAML. The payload you provide must match the one you provided when generating the updated script.

See the config object description for parameter definitions, value types, and additional configuration options.

Username and password authentication example

This request updates the configuration to enable query audit in Snowflake.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": true
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "taylor@snowflake.com",
      "password": "abc1234"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Pass the same payload you sent when generating the script, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.

Snowflake key pair authentication example

This request updates the configuration to enable query audit in Snowflake.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "audit": {
        "enabled": true
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "authenticationType": "keyPair",
      "username": "SYSTEM_ACCOUNT",
      "privateKey": "-----BEGIN PRIVATE KEY-----\n<first line of private key content>\n<another line of private key content>\n<another line of private key content>\n-----END PRIVATE KEY-----"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Pass the same payload you sent when generating the script, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.

   • privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: . If you are using another means of configuration, such as a Python script, the should not be added.

   • connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.

Snowflake External OAuth authentication example

This request updates the configuration to disable Snowflake workspaces and enable Snowflake query audit for the integration.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Snowflake",
    "autoBootstrap": false,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "impersonation": {
        "enabled": true,
        "role": "IMMUTA_IMPERSONATION"
      },
      "audit": {
        "enabled": true
      },
      "workspaces": {
        "enabled": false
      },
      "authenticationType": "oAuthClientCredentials",
      "oAuthClientConfig": {
        "provider": "Okta",
        "clientId": "123456abc",
        "useCertificate": false,
        "clientSecret": "secret",
        "authorityUrl": "example.authority.com"
      }
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Pass the same payload you sent when generating the script, where

   • host is the URL of your Snowflake account.

   • warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

   • database is the name of a new empty database that the Immuta system user will manage and store metadata in.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.

   • workspaces specifies whether Immuta project workspaces are enabled for Snowflake. See the object description for details about child parameters.

   • oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.

Response

The response returns the status of the Snowflake integration configuration. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Basic Connection Test",
      "status": "passed"
    },
    {
      "name": "Initial Validation: Default Warehouse Access Test",
      "status": "passed",
      "result": []
    },
    {
      "name": "Initial Validation: Validate access to Privileged Role",
      "status": "passed",
      "result": []
    },
    {
      "name": "Validate Automatic: Database Does Not Exist",
      "status": "passed"
    },
    {
      "name": "Validate Automatic: Impersonation Role Does Not Exist",
      "status": "skipped"
    },
    {
      "name": "Validate Automatic Bootstrap User Grants",
      "status": "passed"
    }
    ]
  }
}