1 of 5

Reference Guides

The reference guides in this section define the integrations API endpoints, request and body parameters, and response schema.

Integrations API endpoints

The integrations API endpoints allow you to create, update, get, and delete integrations and generate scripts to run in your data platform to manually set up or remove Immuta-managed resources.

Consult this guide for endpoint descriptions and examples.

Integrations API payloads and objects

The integrations API request payloads accept JSON or YAML format, and each integration has parameters and objects specific to the data platform.

Consult this guide for parameter value types, requirements, definitions, and accepted values.

Response schema

The response returns the status of the integration configuration in JSON format.

Consult this guide for response schema definitions and integration state definitions.

HTTP status codes and error messages

The integrations API uses standard HTTP status codes. Status codes specific to the integrations API are described in this reference guide.

Consult this guide for a list of status codes, integration states, common error messages, and troubleshooting guidance.

Integration Configuration Payload

The parameters for configuring an integration in Immuta are outlined in the table below.

Parameter

Description

Required or optional

Default values

Accepted values

Amazon S3 configuration object

The config object configures the S3 integration. The table below outlines its child parameters.

Parameter

Description

Required or optional

Default values

Accepted values

S3 data sources

The table below outlines the parameters for creating an S3 data source.

S3 data source response schema

The table below outlines the response schema for successful requests.

Azure Synapse Analytics configuration objects

The config object configures the Azure Synapse Analytics integration. The table below outlines its child parameters.

Azure Synapse Analytics impersonation object

The impersonation object enables and defines roles for user impersonation for Azure Synapse Analytics. The table below outlines its child parameters.

Delete Azure Synapse Analytics payload

The credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.

Metadata delimiters object

The metadataDelimiters object specifies the delimiters that Immuta uses to store profile data in Azure Synapse Analytics. The table below outlines its child parameters.

Databricks Unity Catalog configuration objects

The config object configures the Databricks Unity Catalog integration. The table below outlines its child parameters.

Additional workspace connections

The additionalWorkspaceConnections array allows you to configure additional workspace connections for your Databricks Unity Catalog integration. The table below outlines its child attributes.

Databricks Unity Catalog audit object

The audit object enables Databricks Unity Catalog query audit. The table below outlines its child parameter.

Group pattern object

The groupPattern object excludes the listed group from having data policies applied in the Databricks Unity Catalog integration. This account-level group should be used for privileged users and service accounts that require an unmasked view of data. The table below outlines its child parameters.

Databricks Unity Catalog proxy options object

The proxyOptions object represents your proxy server configuration in Databricks Unity Catalog. The table below outlines the object's child attributes.

Databricks Unity Catalog OAuth configuration object

Google BigQuery configuration object

The config object configures the Google BigQuery integration. The table below outlines its child parameters.

Redshift configuration objects

The config object configures the Redshift integration. The table below outlines its child parameters.

Delete Redshift integration payload

The authentication type and credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.

Redshift impersonation object

The impersonation object enables and defines roles for user impersonation for Redshift. The table below outlines its child parameters.

Okta object

The okta object represents your Okta configuration. This object is required if you set okta as your authentication type in the Redshift integration configuration. The table below outlines its child parameters.

Snowflake configuration objects

The config object configures the Snowflake integration. The table below outlines its child parameters.

Audit object

The audit object enables Snowflake query audit. The table below outlines its child parameter.

Delete Snowflake integration payload

Snowflake impersonation object

The impersonation object enables and defines roles for user impersonation for Snowflake. The table below outlines its child parameters.

Lineage object

The lineage object enables Snowflake native lineage ingestion. When this setting is enabled, Immuta automatically applies tags added to a Snowflake table to its descendant data source columns in Immuta so you can build policies using those tags to restrict access to sensitive data. The table below outlines its child parameters.

Snowflake OAuth configuration object

The oAuthClientConfig object represents your OAuth configuration in Snowflake. This object is required if you set oAuthClientCredentials as your authentication type in the Snowflake integration configuration, and you must set autoBootstrap to false. The table below outlines the object's child parameters.

User role pattern object

The userRolePattern object excludes roles and users from authorization checks in the Snowflake integration. The table below outlines its child parameter.

Workspaces object

The workspaces object represents an Immuta project workspace configured for Snowflake. The table below outlines its child parameters.

Response Schema

The table below outlines the response schema for all integration configurations.

Property

Description

Integration statuses

The status property in the response schema shows the status of the integration. The table below provides definitions for each status and the state of the integration configuration.

Validation results object

The validationResults object provides details about the status of each test Immuta runs to validate the the integration configuration.

Attribute

Description

Possible values

Amazon S3 validation tests

The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.

Azure Synapse Analytics validation tests

The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.

Databricks Unity Catalog validation tests

The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.

Google BigQuery validation tests

The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.

Redshift validation tests

The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.

Snowflake validation tests

The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.

HTTP Status Codes and Error Messages

The integrations API returns HTTP status codes, error codes, and messages in JSON format.

GET error

The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for the error.

Code

Text

Description

DELETE errors

The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for each error.

Code

Text

Description

POST errors

The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for each error.

Code

Text

Description

PUT errors

The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for each error.

Integrations API Endpoints

The integrations resource allows you to create, configure, and manage your integration. How Immuta manages and administers policies in your data platform varies by integration.

To configure or manage an integration, users must have the APPLICATION_ADMIN Immuta permission.

Endpoints

Method

Endpoint

Description

GET /integrations

Gets all integration configurations.

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",
        "authenticationType": "token",
        "token": "REDACTED",
        "audit": {
          "enabled": false
        },
        "catalog": "immuta"
      }
    }
  }
]

POST /integrations

Creates an integration configuration that allows Immuta to manage access policies on data registered in Immuta.

Amazon S3 example

When you connect Immuta to your AWS account, the awsLocationPath is the base S3 location prefix that Immuta will use for this connection when registering S3 data sources.

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

Azure Synapse Analytics example

When you connect Immuta to your Azure Synapse Analytics account, the schema you specify is where all the policy-enforced views will be created and managed by Immuta.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Azure Synapse Analytics",
    "autoBootstrap": true,
    "config": {
      "host": "organization.azure.com",
      "schema": "sample_schema",
      "database": "immuta",
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

Databricks Unity Catalog example

This request creates a Databricks Unity Catalog integration configuration that allows Immuta to administer Unity Catalog policies on data registered in Immuta.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": true,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "token",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'

Google BigQuery example

When you connect Immuta to your Google BigQuery account, the dataset you specify is where all the policy-enforced views will be created and managed by Immuta.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Google BigQuery",
    "autoBootstrap": false,
    "config": {
      "role": "immuta",
      "datasetSuffix": "_secureView",
      "dataset": "immuta",
      "location": "us-east1",
      "credential": "{\"type\":\"service_account\",\"project_id\":\"innate-conquest-123456\",\"private_key_id\":\"9163c12345690924f5dd218ff39\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\nXXXXXXXro0s\n/yQlPQijowkccmrmWJyr93kdLnwJzBvLHCto/+W\ncvF2ygX9oM/dyUK//z//4nptMp+Ck//Yw3D4rIBwGu4DWiR1qRnf\nDoGyXfThPTQ==\n-----END PRIVATE KEY-----\n\",\"client_email\":\"service-account-id@innate-conquest-123456.iam.gserviceaccount.com\",\"client_id\":\"1166290***432952487857\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"https://www.googleapis.com/robot/v1/metadata/x509/service-accound-id%40innate-conquest-123456.iam.gserviceaccount.com\",\"universe_domain\":\"googleapis.com\"}"
    }
    }'

Redshift example

When you connect Immuta to your Redshift account, the Immuta system user will use the database you specify to manage and store metadata. The initial database (REDSHIFT_SAMPLE_DATA, in the request below) is an existing Redshift database that Immuta connects to in order to create the Immuta-managed database (immuta, in the request below).

This request specifies userPassword as the authentication type for the Immuta system user. The username and password provided are credentials for a system account that can manage the database.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Redshift",
    "autoBootstrap": true,
    "config": {
      "host": "organization.aws.amazon.com",
      "database": "immuta",
      "initialDatabase": "REDSHIFT_SAMPLE_DATA",
      "authenticationType": "userPassword",
      "username": "taylor@redshift.com",
      "password": "abc1234"
    }
    }'

Snowflake example

When you connect Immuta to your Snowflake account, the warehouse you specify is the default pool of compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

This request specifies userPassword authentication type. The username and password provided are credentials of a Snowflake account attached to a role with these privileges. These credentials are not stored; they are used by Immuta to configure 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": "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"
    }
    }'

Starburst (Trino) example

When you configure the Starburst (Trino) integration, Immuta generates an API key and configuration snippet on the Immuta app settings page that you will use to configure your Starburst cluster.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Trino"
    }'

Body parameters

The request accepts a JSON or YAML payload with the parameters outlined below.

Parameter

Description

Required or optional

Default values

Accepted values

Query parameter

Parameter

Description

Required or optional

Response

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

A successful response includes the validation tests statuses.

{
  "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"
    }
    ]
  }
}

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.

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

DELETE /integrations/{id}

Deletes the integration configuration you specify in the request.

curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/123456789' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "authenticationType": "userPassword",
    "username": "taylor@snowflake.com",
    "password": "abc1234",
    "role": "ACCOUNTADMIN"
    }'

Request parameter

Parameter

Description

Required or optional

Query parameter

Parameter

Description

Required or optional

Body parameters

For Amazon S3 integrations, Databricks Unity Catalog integrations, Google BigQuery integrations, Starburst (Trino) integrations, or integration configurations with autoBootstrap set to false, no payload is required to delete the integration.

For the integrations below, the request accepts a JSON or YAML payload when autoBootstrap is set to true. See the payload description for your integration for parameters and details:

Delete Azure Synapse Analytics integration payload
Delete Redshift integration payload
Delete Snowflake integration payload

Response

The response returns the status of the 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": "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"
    }
    ]
  }
}

GET /integrations/{id}

Gets the integration configuration you specify in the request.

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

Request parameter

Parameter

Description

Required or optional

Response

The response returns an 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",
      "result": [],
      "status": "passed"
    }, {
      "name": "Initial Validation: Table Grants Role Prefix is Unique",
      "status": "passed"
    }, {
      "name": "Initial Validation: Validate access to Privileged Role",
      "result": [],
      "status": "passed"
    }, {
      "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"
  }
}

PUT /integrations/{id}

Updates an existing integration configuration.

Amazon S3 example

This request changes the name of the integration.

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

Azure Synapse Analytics example

This request enables user impersonation for the Azure Synapse Analytics integration.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/123456789' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Azure Synapse Analytics",
    "autoBootstrap": true,
    "config": {
      "host": "organization.azure.com",
      "schema": "sample_schema",
      "database": "immuta",
      "impersonation": {
        "enabled": true,
        "role": "IMMUTA_IMPERSONATION"
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

Databricks Unity Catalog example

This request updates the access token.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/123456789' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": true,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "token",
      "token": "REDACTED",
      "groupPattern": {
        "deny": "admins"
      },
      "catalog": "immuta"
    }
    }'

Google BigQuery example

This request updates the private key for the Google BigQuery 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": "Google BigQuery",
    "autoBootstrap": false,
    "config": {
      "role": "immuta",
      "datasetSuffix": "_secureView",
      "dataset": "immuta",
      "location": "us-east1",
      "credential": "{\"type\":\"service_account\",\"project_id\":\"innate-conquest-123456\",\"private_key_id\":\"9163c12345690924f5dd218ff39\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\nXXXXXXXro0s\n/yQlPQijowkccmrmWJyr93kdLnwJzBvLHCto/+W\ncvF2ygX9oM/dyUK//z//4nptMp+Ck//Yw3D4rIBwGu4DWiR1qRnf\nDoGyXfThPTQ==\n-----END PRIVATE KEY-----\n\",\"client_email\":\"service-account-id@innate-conquest-123456.iam.gserviceaccount.com\",\"client_id\":\"1166290***432952487857\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"https://www.googleapis.com/robot/v1/metadata/x509/service-accound-id%40innate-conquest-123456.iam.gserviceaccount.com\",\"universe_domain\":\"googleapis.com\"}"
    }
    }'

Redshift example

This request enables user impersonation for the Redshift integration.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/123456789' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Redshift",
    "autoBootstrap": true,
    "config": {
      "host": "organization.aws.amazon.com",
      "database": "immuta",
      "initialDatabase": "REDSHIFT_SAMPLE_DATA",
      "impersonation": {
        "enabled": true,
        "role": "immuta_impersonation"
      },
      "authenticationType": "okta",
      "okta": {
        "username": "taylor@redshift.com",
        "password": "abc1234",
        "appId": "Okta",
        "idpHost": "organization.okta.com",
        "role": "admin"
      }
    }
    }'

Snowflake example

This request enables auditing queries run in Snowflake.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/123456789' \
    -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"
    }
    }'

Body parameters

The request accepts a JSON or YAML payload with the parameters outlined below.

Parameter

Description

Required or optional

Default values

Accepted values

Query parameter

Parameter

Description

Required or optional

Response

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

A successful response includes the validation tests statuses.

{
  "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"
    }
    ]
  }
}

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.

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

POST /integrations/{id}/regenerate

Regenerates an Immuta API key for the configured integration.

Starburst (Trino) example

This request regenerates an Immuta API key for the configured Starburst (Trino) integration. Once you make this request, your old Immuta API key will be deleted and will no longer be valid. See the Configure a Starburst (Trino) integration page for instructions on updating your Starburst (Trino) integration to use the new API key.

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

Response

The response returns the new Immuta API key. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages page for a list of statuses, error messages, and troubleshooting guidance.

{ "newKey": "5bb6cae9******300c21acbb" }

GET /integrations/{id}/status

Gets the status of the integration specified in the request.

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

Request parameter

Parameter

Description

Required or optional

Response

The response returns the status of the specified integration. An unsuccessful request returns the HTTP 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"}

POST /integrations/scripts/cleanup

Creates a script to remove Immuta-managed resources from your platform. This endpoint is for Azure Synapse Analytics, Redshift, and Snowflake integrations that were not successfully created and, therefore, do not have an integration ID.

For Azure Synapse Analytics integrations, you must also make a request to the /integrations/scripts/post-cleanup endpoint to create another script that will finish removing Immuta-managed resources from the platform.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/cleanup' \
    -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": "IMMUTA_SYSTEM_ACCOUNT",
      "password": "abc1234"
    }
    }'

Body parameters

The request accepts a JSON or YAML payload with the parameters outlined below.

Parameter

Description

Required or optional

Default values

Accepted values

Response

The response returns the script that you will run in your Azure Synapse Analytics, Redshift, or Snowflake environment.

Once you have run the script,

use the DELETE /integrations/{id} endpoint to delete your Redshift or Snowflake integration in Immuta:
- Delete Redshift integration
- Delete Snowflake integration
use the /integrations/scripts/post-cleanup endpoint to create another script that will finish removing Immuta-managed resources from your Azure Synapse Analytics platform.

POST /integrations/scripts/create

Creates a script for you to run manually to set up objects and resources for Immuta to manage and enforce access controls on your data. This endpoint is available for Azure Synapse Analytics, Databricks Unity Catalog, Redshift, and Snowflake integrations.

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": "IMMUTA_SYSTEM_ACCOUNT",
      "password": "abc1234"
    }
    }'

Body parameters

The request accepts a JSON or YAML payload with the parameters outlined below.

Parameter

Description

Required or optional

Default values

Accepted values

Response

The response returns the script that you will run in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment.

POST /integrations/{id}/scripts/delete

Creates a script to remove Immuta-managed resources from your platform. This endpoint is for Azure Synapse Analytics, Redshift, and Snowflake integrations that were successfully created.

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

Response

The response returns the script that you will run in your Azure Synapse Analytics, Redshift, or Snowflake environment.

Once you have run the script, use the DELETE /integrations/{id} endpoint to delete your integration in Immuta:

POST /integrations/{id}/scripts/edit

Creates a script for you to run manually to edit objects and resources managed by Immuta in your platform. This endpoint is available for Azure Synapse Analytics, Databricks Unity Catalog, Redshift, and Snowflake integrations.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/1/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": "IMMUTA_SYSTEM_ACCOUNT",
      "password": "abc1234"
    }
    }'

Body parameters

The request accepts a JSON or YAML payload with the parameters outlined below.

Parameter

Description

Required or optional

Default values

Accepted values

Response

The response returns the script that you will run in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment. Once you have run the script, use the PUT /integrations/{id} endpoint to finish editing your integration:

POST /integrations/scripts/initial-create

Creates the first script for you to run manually to set up objects and resources for Immuta to manage and enforce access controls on your data in Azure Synapse Analytics or Redshift integrations.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/initial-create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Azure Synapse Analytics",
    "autoBootstrap": false,
    "config": {
      "host": "organization.azure.com",
      "schema": "sample_schema",
      "database": "immuta",
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

Body parameters

The request accepts a JSON or YAML payload with the parameters outlined below.

Parameter

Description

Required or optional

Default values

Accepted values

Response

The response returns the script that you will run in your Azure Synapse Analytics or Redshift environment.

Once you have run this script, use the /integrations/scripts/create endpoint to generate a script to finish creating the Immuta-managed resources in your platform.

POST /integrations/scripts/post-cleanup

Creates a second script to remove the final Immuta-managed resources from your Azure Synapse Analytics platform. This endpoint is for Azure Synapse Analytics integrations that were not successfully created and, therefore, do not have an integration ID.

Before making a request like the one below, you must make a request to the /integrations/scripts/cleanup endpoint to create the first script that will remove the initial Immuta-managed resources from the platform.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/post-cleanup' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Azure Synapse Analytics",
    "autoBootstrap": false,
    "config": {
      "host": "organization.azure.com",
      "schema": "sample_schema",
      "database": "immuta",
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

Body parameters

The request accepts a JSON or YAML payload with the parameters outlined below.

Parameter

Description

Required or optional

The table below outlines the response schema for successful requests.

Property

Description

Azure Synapse Analytics configuration objects

The config object configures the Azure Synapse Analytics integration. The table below outlines its child parameters.

Parameter

Description

Required or optional

Default values

Accepted values

Azure Synapse Analytics impersonation object

The impersonation object enables and defines roles for user impersonation for Azure Synapse Analytics. The table below outlines its child parameters.

Parameter

Description

Default values

Accepted values

Delete Azure Synapse Analytics payload

Parameter

Description

Required or optional

Accepted values

The audit object enables Databricks Unity Catalog query audit. The table below outlines its child parameter.

Parameter

Description

Default values

Parameter

Description

Required or optional

Accepted values

Redshift impersonation object

The impersonation object enables and defines roles for user impersonation for Redshift. The table below outlines its child parameters.

Parameter

Description

Default values

Accepted values

Okta object

Parameter

Description

Required or optional

Default values

Accepted values

Snowflake configuration objects

The config object configures the Snowflake integration. The table below outlines its child parameters.

Parameter

Description

Required or optional

Default values

Accepted values

Audit object

The audit object enables Snowflake query audit. The table below outlines its child parameter.

Parameter

Description

Default values

Accepted values

The workspaces object represents an Immuta project workspace configured for Snowflake. The table below outlines its child parameters.

Parameter

Description

Default values

Accepted values