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
POST	/integrations	Creates an integration
DELETE	/integrations/{id}	Deletes a configured integration
GET	/integrations/{id}	Gets an integration configuration
PUT	/integrations/{id}	Updates a configured integration
POST	/integrations/{id}/regenerate	Regenerates an Immuta API key for the configured integration
GET	/integrations/{id}/status	Gets the status of the specified integration
POST	/integrations/scripts/cleanup	Creates a script to remove Immuta-managed resources from your platform for integrations that were not successfully created
POST	/integrations/scripts/create	Creates a script to set up Immuta-managed resources in your platform
POST	/integrations/{id}/scripts/delete	Creates a script to remove Immuta-managed resources from your platform for integrations that were successfully configured
POST	/integrations/{id}/scripts/edit	Creates a script to edit existing Immuta-managed resources in your platform
POST	/integrations/scripts/initial-create	Creates the first script to set up Immuta-managed resources in your Azure Synapse Analytics or Redshift platform
POST	/integrations/scripts/post-cleanup	Creates the second script to remove Immuta-managed resources from your Azure Synapse Analytics integration if it was not successfully created

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": "[e-mail]",
      "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\":\"[e-mail]\",\"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": "[e-mail]",
      "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": "[e-mail]",
      "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
type string	The type of integration to configure.	Required	-	Azure Synapse Analytics Databricks Google BigQuery Native S3 Redshift Snowflake Trino
autoBootstrap boolean	When true, Immuta will automatically configure the integration in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment for you. When false, you must set up your environment manually before configuring the integration with the API. This parameter must be set to false in the Amazon S3 and Google BigQuery configurations. See the specific how-to guide for configuring your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, Snowflake.	Required for all integrations except Starburst (Trino)	-	true or false
config object	This object specifies the integration settings. See the config object description for your integration for details: Amazon S3, Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake.	Required for all integrations except Starburst (Trino)	-	-

Query parameter

Parameter	Description	Required or optional
dryRun boolean	When true, the integration configuration will not actually be created, and the response returns the validation tests statuses.	Optional

Response

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

200 response

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

Unsuccessful request

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": "[e-mail]",
    "password": "abc1234",
    "role": "ACCOUNTADMIN"
    }'

Request parameter

Parameter	Description	Required or optional
id number	The unique identifier of the integration configuration.	Required

Query parameter

Parameter	Description	Required or optional
dryRun boolean	When true, the integration configuration will not actually be deleted, and the response returns the validation tests statuses.	Optional
forceDisable boolean	When true, the integration will be deleted in Immuta. Users must manually remove all Immuta objects in the remote data platform.	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
id number	The unique identifier of the integration configuration.	Required

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": "[e-mail]",
      "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",
      "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\":\"[e-mail]\",\"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": "[e-mail]",
        "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": "[e-mail]",
      "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
type string	The type of integration to configure.	Required	-	Azure Synapse Analytics Databricks Google BigQuery Redshift Snowflake
autoBootstrap boolean	When true, Immuta will automatically configure the integration in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment for you. When false, you must set up your environment manually before configuring the integration with the API. This parameter must be set to false in the Google BigQuery configuration. See the specific how-to guide for configuring other integrations: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, Snowflake.	Required	-	true or false
config object	This object specifies the integration settings. See the config object description for your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake.	Required	-	-

Query parameter

Parameter	Description	Required or optional
dryRun boolean	When true, the integration configuration will not actually be updated, and the response returns the validation tests statuses.	Optional

Response

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

200 response

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

Unsuccessful request

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
id number	The unique identifier of the integration configuration.	Required

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
type string	The type of integration to clean up.	Required	-	Azure Synapse Analytics Redshift Snowflake
autoBootstrap boolean	Set to false to specify that you will run the script in your environment yourself to clean up the integration resources. See the Azure Synapse Analytics, Redshift, or Snowflake manual setup section for details.	Required	-	false
config object	This object specifies the integration settings. See the config object description for your integration for details: Azure Synapse Analytics, Redshift, or Snowflake.	Required	-	-

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
type string	The type of integration to configure.	Required	-	Azure Synapse Analytics Databricks Redshift Snowflake
autoBootstrap boolean	Set to false to specify that you will run the script in your environment yourself to configure the integration. You must run the Immuta script before creating the integration. See the Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake manual setup guides for details.	Required	-	false
config object	This object specifies the integration settings. See the config object description for your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake.	Required	-	-

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:

• Delete Azure Synapse Analytics integration
• Delete Redshift integration
• Delete Snowflake integration

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, 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
type string	The type of integration to configure.	Required	-	Azure Synapse Analytics Databricks Redshift Snowflake
autoBootstrap boolean	Set to false to specify that you will run the script in your environment yourself to configure the integration. You must run the Immuta script before creating the integration. See the Azure Synapse Analytics, Redshift, or Snowflake manual setup guides for details.	Required	-	false
config object	This object specifies the integration settings. Some settings cannot be changed once an integration is configured. See the config object description for your integration for details: Azure Synapse Analytics, Redshift, or Snowflake.	Required	-	-

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 PUT /integrations/{id} endpoint to finish editing your integration:

• Configure Azure Synapse Analytics integration
• Configure Redshift integration
• Configure Snowflake 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": "[e-mail]",
      "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
type string	The type of integration to configure.	Required	-	Azure Synapse Analytics Redshift
autoBootstrap boolean	Set to false to specify that you will run the script in your environment yourself to configure the integration. You must run the Immuta script before creating the integration. See the Azure Synapse Analytics or Redshift manual setup guides for details.	Required	-	false
config object	This object specifies the integration settings. See the config object description of the Azure Synapse Analytics or Redshift integration configuration for details.	Required	-	-

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": "[e-mail]",
      "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
type string	The type of integration to clean up.	Required	-	Azure Synapse Analytics
autoBootstrap boolean	Set to false to specify that you will run the script in your environment yourself to clean up the integration resources. See the Azure Synapse Analytics manual setup section for details.	Required	-	false
config object	This object specifies the integration settings. See the config object description of Azure Synapse Analytics for details.	Required	-	-

Response

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

Once you have run the script, use the DELETE /integrations/{id} endpoint to delete your integration in Immuta by following the Delete Azure Synapse Analytics integration instructions.

Related guides

See the following how-to guides for configuration examples and steps for creating, managing, or deleting your integration:

• Configure an Amazon S3 integration
• Configure an Azure Synapse Analytics integration
• Configure a Databricks Unity Catalog integration
• Configure a Google BigQuery integration
• Configure a Redshift integration
• Configure a Snowflake integration
• Configure a Starburst (Trino) integration