LogoLogo
SaaS
  • Immuta Documentation - SaaS
  • Configuration
    • Connect Data Platforms
      • Data Platforms Overview
      • Amazon S3 Integration
      • AWS Lake Formation
        • Getting Started with AWS Lake Formation
        • Register an AWS Lake Formation Connection
        • Reference Guides
          • AWS Lake Formation
          • Security and Compliance
          • Protecting Data
          • Accessing Data
      • Azure Synapse Analytics
        • Getting Started with Azure Synapse Analytics
        • Configure Azure Synapse Analytics Integration
        • Reference Guides
          • Azure Synapse Analytics Overview
          • Azure Synapse Analytics Pre-Configuration Details
      • Databricks
        • Databricks Spark
          • Getting Started with Databricks Spark
          • How-to Guides
            • Configure a Databricks Spark Integration
            • Manually Update Your Databricks Cluster
            • Install a Trusted Library
            • Project UDFs Cache Settings
            • Run R and Scala spark-submit Jobs on Databricks
            • DBFS Access
            • Troubleshooting
          • Reference Guides
            • Databricks Spark Integration Configuration
              • Installation and Compliance
              • Customizing the Integration
              • Setting Up Users
              • Spark Environment Variables
              • Ephemeral Overrides
            • Security and Compliance
            • Registering and Protecting Data
            • Accessing Data
              • Delta Lake API
        • Databricks Unity Catalog
          • Getting Started with Databricks Unity Catalog
          • How-to Guides
            • Configure a Databricks Unity Catalog Integration
            • Migrating to Unity Catalog
          • Databricks Unity Catalog Integration Reference Guide
      • Google BigQuery Integration
      • Redshift
        • Getting Started with Redshift
        • How-to Guides
          • Configure Redshift Integration
          • Configure Redshift Spectrum
        • Reference Guides
          • Redshift Overview
          • Redshift Pre-Configuration Details
      • Snowflake
        • Getting Started with Snowflake
        • How-to Guides
          • Configure a Snowflake Integration
          • Edit or Remove Your Snowflake Integration
          • Integration Settings
            • Snowflake Table Grants Private Preview Migration
            • Enable Snowflake Table Grants
            • Using Snowflake Data Sharing with Immuta
            • Enable Snowflake Low Row Access Policy Mode
              • Upgrade Snowflake Low Row Access Policy Mode
            • Configure Snowflake Lineage Tag Propagation
        • Reference Guides
          • Snowflake Integration
          • Snowflake Table Grants
          • Snowflake Data Sharing with Immuta
          • Snowflake Low Row Access Policy Mode
          • Snowflake Lineage Tag Propagation
          • Warehouse Sizing Recommendations
        • Explanatory Guides
          • Phased Snowflake Onboarding
      • Starburst (Trino)
        • Getting Started with Starburst (Trino)
        • How-to Guides
          • Configure Starburst (Trino) Integration
          • Customize Read and Write Access Policies for Starburst (Trino)
        • Starburst (Trino) Integration Reference Guide
      • Queries Immuta Runs in Your Data Platform
      • Connect Your Data
        • Registering a Connection
          • How-to Guides
            • Register a Snowflake Connection
            • Register a Databricks Unity Catalog Connection
            • Manually Run Object Sync
            • Manage Connection Settings
            • Use the Connection Upgrade Manager
              • Troubleshooting
          • Reference Guides
            • Connections
            • Upgrading to Connections
              • Before You Begin
              • API Changes
              • FAQ
        • Registering Metadata
          • Data Sources in Immuta
          • Register Data Sources
            • Amazon S3 Data Source
            • Azure Synapse Analytics Data Source
            • Databricks Data Source
            • Google BigQuery Data Source
            • Redshift Data Source
            • Snowflake Data Source
              • Bulk Create Snowflake Data Sources
            • Create a Starburst (Trino) Data Source
          • Data Source Settings
            • How-to Guides
              • Manage Data Source Settings
              • Manage Data Source Members
              • Manage Access Requests and Tasks
              • Manage Data Dictionary Descriptions
              • Disable Immuta from Sampling Raw Data
            • Data Source Health Checks Reference Guide
          • Schema Monitoring
            • How-to Guides
              • Manage Schema Monitoring
              • Run Schema Monitoring and Column Detection Jobs
            • Reference Guides
              • Schema Monitoring
              • Schema Projects
            • Why Use Schema Monitoring Concept Guide
    • Manage Data Metadata
      • Connect External Catalogs
        • Configure an External Catalog
        • Reference Guides
          • External Catalog Introduction
          • Custom REST Catalog Interface Introduction
          • Custom REST Catalog Interface Endpoints
      • Data Discovery
        • Introduction
        • Getting Started with Data Discovery
        • How-to Guides
          • Use Identifiers in Domains
          • Use Sensitive Data Discovery (SDD)
          • Manage Identification Frameworks
          • Manage Identifiers
          • Run and Manage Sensitive Data Discovery on Data Sources
        • Reference Guides
          • Identifiers in Domains
          • Built-in Identifier Reference
          • Improved Pack: Built-in Identifier Reference
          • Built-in Discovered Tags Reference
          • How Competitive Pattern Analysis Works
      • Data Classification
        • How-to Guides
          • Activate Classification Frameworks
          • Adjust Identification and Classification Framework Tags
          • How to Use a Classification Framework with Your Own Tags
        • Reference Guide
          • Classification Frameworks
      • Manage Tags
        • How-to Guides
          • Create and Manage Tags
          • Add Tags to Data Sources and Projects
        • Tags Reference Guide
    • Manage Users
      • Getting Started with Users
      • Identity Managers (IAMs)
        • How-to Guides
          • Okta LDAP Interface
          • OpenID Connect
            • OpenID Connect Protocol
            • Okta and OpenID Connect
            • OneLogin with OpenID Connect
          • SAML
            • SAML Protocol
            • Microsoft Entra ID
            • Okta SAML SCIM
        • Reference Guides
          • Identity Managers
          • SAML Protocol Configuration Options
          • SAML Single Logout
      • Immuta Users
        • How-to Guides
          • Managing Personas and Permissions
          • User Impersonation
          • Manage Attributes and Groups
          • External User ID Mapping
          • External User Info Endpoint
        • Reference Guides
          • Permissions and Personas
          • Attributes and Groups in Immuta
    • Organize Data into Domains
      • Getting Started with Domains
      • Domains Reference Guide
    • Application Settings
      • How-to Guides
        • App Settings
        • Private Networking Support
          • Data Connection Private Networking
            • AWS PrivateLink for Redshift
            • AWS PrivateLink for API Gateway
            • Databricks Private Connectivity
              • AWS PrivateLink for Databricks
              • Azure Private Link for Databricks
            • Snowflake Private Connectivity
              • AWS PrivateLink for Snowflake
              • Azure Private Link for Snowflake
            • Starburst (Trino) Private Connectivity
              • AWS PrivateLink for Starburst (Trino)
              • Azure Private Link for Starburst (Trino)
          • Immuta SaaS Private Networking
            • Immuta SaaS Private Networking Over AWS PrivateLink
        • BI Tools
          • BI Tool Configuration Recommendations
          • Power BI Configuration Example
          • Tableau Configuration Example
        • IP Filtering
        • System Status Bundle
      • Reference Guides
        • Deployment Options
        • Data Processing
        • Encryption and Masking Practices
  • Marketplace
    • Introduction
      • User Types
      • Walkthrough
    • Share Data Products
      • How-to Guides
        • Manage Data Products
        • View and Respond to Access Requests
        • Customize the Marketplace Branding
      • Reference Guides
        • Marketplace App Requirements
        • Data Products
        • Marketplace Permissions Matrix
        • Understanding Access Provisioning and Underlying Policies in Immuta
          • S3 Provisioning Best Practices
        • Integrating with Existing Catalogs
        • Setting Up Domains for Marketplace
    • Access Data Products
      • How-to Guides
        • Logging into Marketplace
        • Requesting Access to a Data Product
      • Reference Guide
        • Data Source Access Status
    • Short-Term Limitations
  • Governance
    • Introduction
      • Automate Data Access Control Decisions
        • The Two Paths
        • Managing User Metadata
        • Managing Data Metadata
        • Author Policy
        • Test and Deploy Policy
      • Compliantly Open More Sensitive Data for ML and Analytics
        • Managing User Metadata
        • Managing Data Metadata
        • Author Policy
    • Author Policies for Data Access Control
      • Introduction
        • Scalability and Evolvability
        • Understandability
        • Distributed Stewardship
        • Consistency
        • Availability of Data
      • Policies
        • Authoring Policies at Scale
        • Data Engineering with Limited Policy Downtime
        • Subscription Policies
          • Overview
          • How-to Guides
            • Author a Subscription Policy
            • Author an ABAC Subscription Policy
            • Subscription Policies Advanced DSL Guide
            • Author a Restricted Subscription Policy
            • Clone, Activate, or Stage a Global Policy
          • Reference Guides
            • Subscription Policy Access Types
            • Advanced Use of Special Functions
        • Data Policies
          • Overview
          • How-to Guides
            • Author a Masking Data Policy
            • Author a Minimization Policy
            • Author a Purpose-Based Restriction Policy
            • Author a Restricted Data Policy
            • Author a Row-Level Policy
            • Author a Time-Based Restriction Policy
            • Policy Certifications and Diffs
          • Reference Guides
            • Data Policy Types
            • Masking Policies
            • Row-Level Policies
            • Custom WHERE Clause Functions
            • Data Policy Conflicts and Fallback
            • Custom Data Policy Certifications
            • Orchestrated Masking Policies
      • Projects and Purpose-Based Access Control
        • Projects and Purpose Controls
          • Getting Started
          • How-to Guides
            • Create a Project
            • Create and Manage Purposes
            • Adjust a Policy
            • Project Management
              • Manage Projects and Project Settings
              • Manage Project Data Sources
              • Manage Project Members
          • Reference Guides
            • Projects and Purposes
            • Policy Adjustments
          • Concept Guide
            • Why Use Purposes?
        • Equalized Access
          • Manage Project Equalization How-to Guide
          • Equalized Access Reference Guide
          • Why Use Project Equalization?
        • Masked Joins
          • Enable Masked Joins How-to Guide
          • Why Use Masked Joins?
        • Writing to Projects
          • How-to Guides
            • Create and Manage Snowflake Project Workspaces
            • Create and Manage Databricks Spark Project Workspaces
            • Write Data to the Workspace
          • Reference Guides
            • Writing to Projects
            • Project UDFs (Databricks)
      • Data Consumers
        • Subscribe to a Data Source
        • Query Data
          • Querying Snowflake Data
          • Querying Databricks Data
          • Querying Starburst (Trino) Data
          • Querying Databricks SQL Data
          • Querying Redshift Data
          • Querying Azure Synapse Analytics Data
        • Subscribe to Projects
    • Observe Access and Activity
      • Introduction
      • Audit
        • How-to Guides
          • Export Audit Logs to S3
          • Export Audit Logs to ADLS
          • Use Immuta Audit
          • Run Governance Reports
        • Reference Guides
          • Universal Audit Model (UAM)
            • UAM Schema Reference Guide
          • Query Audit Logs
            • Snowflake Query Audit Logs
            • Databricks Unity Catalog Query Audit Logs
            • Databricks Spark Query Audit Logs
            • Starburst (Trino) Query Audit Logs
          • Audit Export GraphQL Reference Guide
          • Unknown Users in Audit Logs
          • Governance Report Types
        • Deprecated Audit Guides
          • Legacy to UAM Migration
          • Manage Audit Logs
      • Dashboards
        • Use the Audit Dashboards How-To Guide
        • Audit Dashboards Reference Guide
      • Monitors
        • Manage Monitors and Observations
        • Monitors Reference Guide
  • Releases
    • Deployment Notes
      • 2024
      • 2023
      • 2022
    • Scheduled Maintenance Windows
    • Immuta Support Matrix Overview
    • Immuta CLI Release Notes
    • Preview Features
      • Features in Preview
    • Deprecations
  • Developer Guides
    • The Immuta CLI
      • Install and Configure the Immuta CLI
      • Manage Your Immuta Tenant
      • Manage Data Sources
      • Manage Sensitive Data Discovery
        • Manage Sensitive Data Discovery Rules
        • Manage Identification Frameworks
        • Run Sensitive Data Discovery on Data Sources
      • Manage Policies
      • Manage Projects
      • Manage Purposes
      • Manage Audit Export
    • The Immuta API
      • Integrations API
        • Getting Started
        • How-to Guides
          • 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
        • Reference Guides
          • Integrations API Endpoints
          • Integration Configuration Payload
          • Response Schema
          • HTTP Status Codes and Error Messages
      • Connections API
        • How-to Guides
          • Register a Connection
            • Register a Snowflake Connection
            • Register a Databricks Unity Catalog Connection
            • Register an AWS Lake Formation Connection
          • Manage a Connection
          • Deregister a Connection
        • Connection Registration Payloads Reference Guide
      • Marketplace API
        • Marketplace API Endpoints
        • Source Controlling Data Products
      • Immuta V2 API
        • Data Source Payload Attribute Details
          • Data Source Request Payload Examples
        • Create Policies API Examples
        • Create Projects API Examples
        • Create Purposes API Examples
      • Immuta V1 API
        • Authenticate with the API
        • Configure Your Instance of Immuta
          • Get Job Status
          • Manage Frameworks
          • Manage IAMs
          • Manage Licenses
          • Manage Notifications
          • Manage Sensitive Data Discovery (SDD)
          • Manage Tags
          • Manage Webhooks
          • Search Filters
        • Connect Your Data
          • Create and Manage an Amazon S3 Data Source
          • Create an Azure Synapse Analytics Data Source
          • Create a Databricks Data Source
          • Create a Redshift Data Source
          • Create a Snowflake Data Source
          • Create a Starburst (Trino) Data Source
          • Manage the Data Dictionary
        • Use Domains
        • Manage Data Access
          • Manage Access Requests
          • Manage Data and Subscription Policies
          • Manage Write Policies
            • Write Policies Payloads and Response Schema Reference Guide
          • Policy Handler Objects
          • Search Audit Logs
          • Search Connection Strings
          • Search for Organizations
          • Search Schemas
        • Subscribe to and Manage Data Sources
        • Manage Projects and Purposes
          • Manage Projects
          • Manage Purposes
        • Generate Governance Reports
Powered by GitBook

Self-managed versions

  • 2024.3
  • 2024.2

Resources

  • Immuta Changelog

Copyright © 2014-2025 Immuta Inc. All rights reserved.

On this page
  • Integration statuses
  • Validation results object
  • Amazon S3 validation tests
  • Azure Synapse Analytics validation tests
  • Databricks Unity Catalog validation tests
  • Google BigQuery validation tests
  • Redshift validation tests
  • Snowflake validation tests

Was this helpful?

Export as PDF
  1. Developer Guides
  2. The Immuta API
  3. Integrations API
  4. Reference Guides

Response Schema

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

Property
Description

id number

The unique identifier of the integration.

config object

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.

Status
Description
State

createError

Error occurred during creation of the integration.

In use

creating

Integration is in the process of being created and set up.

In use

deleted

Integration is deleted.

Not in use

deleteError

Error occurred while deleting the integration. The integration has been rolled back to the previous state.

In use

deleting

Integration is in the process of being disabled or deleted.

In use

disabled

Integration was force disabled and no cleanup was performed on the remote platform.

Not in use

editError

Error occurred while editing the integration. The integration has been rolled back to the previous state.

In use

editing

The integration is in the process of being edited.

In use

enabled

The integration is enabled and active.

In use

migrateError

Error occurred while performing a migration of the integration. The integration has been rolled back to the previous state.

In use

migrating

Migration is being performed on the integration. An example of a migration is a stored procedure update.

In use

recurringValidationError

Validation has failed during the periodic check and the integration may be misconfigured.

In use

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

status string

Whether or not the connection validation passed.

  • passed

  • failed

  • warning

  • skipped

validationTests array[]

This array includes the validation tests run on the integration connection.

-

validationTests.name string

The name of the validation test.

See the section corresponding to your integration type for a list of test names and messages:

validationTests.status string

The status of the validation test.

  • passed

  • failed

  • warning

  • skipped

validationTests.message string

When a test fails, the message provides context and guidance for addressing the failure.

See the section corresponding to your integration type for a list of test names and messages:

Amazon S3 validation tests

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

Test name
Description
Message

There is no existing integration matching this configuration

Verifies that the integration configuration does not match an existing one.

-

The provided integration name is unique across Immuta S3 integrations

Verifies that the name of the integration does not match an existing S3 integration name.

"The Immuta service account does not end with expected value."

The provided access grants location role is a valid ARN format

Verifies that the access grants location role is in the correct format.

"The specified access grants location role is not a valid ARN format."

The provided AWS credentials allow fetching the caller's identity via the AWS STS API

Verifies that the integration can use the AWS STS API to get the caller's identity using the provided credentials.

"Found user ID [], ARN [] using STS."

An AWS Access Grants instance is configured in the provided AWS account and region

Verifies that an Access Grants instance has been created in the specified AWS account and region.

"AccessDenied: Unable to retrieve the access grants instance for account, region: AWS responded with code [403], name [AccessDenied] and message [Access Denied] for request ID []."

The provided S3 path exists and Immuta can list prefixes

Verifies that Immuta can access and list prefixes for the provided S3 path.

"Immuta does not have access to the requested path [s3://]. Without access, Immuta will be unable to assist with S3 path discovery during data source creation."

An AWS Access Grants location does not yet exist for the provided path

Verifies that an Access Grants location has not already been registered for the specified S3 path.

"AccessDenied: Unable to list S3 access grants locations for account [], location scope []: AWS responded with code [403], name [AccessDenied] and message [Access Denied] for request ID []."

Azure Synapse Analytics validation tests

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

Test name
Description
Message

Initial validation: connect

Verifies that Immuta can connect to Azure Synapse Analytics.

"Unable to connect to host."

Initial validation: delimiters test

Verifies that the delimiters are unique.

"Hash delimiter and array delimiter must not have the same value."

Validate automatic: impersonation role does not exist

Verifies that the user impersonation role specified in the request payload does not already exist.

"Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name."

Validate Immuta system user can manage database

Verifies that the specified user can manage the database.

"User does not have permission to manage database."

Databricks Unity Catalog validation tests

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

Test name
Description
Message

Basic connection test

Verifies that Immuta can connect to Databricks Unity Catalog.

"Could not connect to host, please confirm you are using valid connection parameters."

Manual catalog setup

Verifies that the catalog and tables used by Immuta are present and have the correct permissions. This test is run when autoBootstrap is false in the Databricks Unity Catalog integration configuration.

"Encountered an error looking up catalog metadata for catalog."

Metastore validation

Verifies that the Unity Catalog metastore is assigned to the specified workspace.

"No metastore is assigned to workspace."

Google BigQuery validation tests

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

Test name
Description
Message

Basic validation: connection can be made to BigQuery

Verifies that Immuta can connect to Google BigQuery.

"Could not connect to the remote BigQuery connection."

Basic validation: Immuta service account postfix

Verifies that the service account ends with the expected value of @<projectId>.iam.gserviceaccount.com.

"The Immuta service account does not end with expected value."

Basic validation: non-matching service account in key file

Verifies that the service account matches the one provided in the keyfile.

"The service account does not match the service account in the provided key file."

Basic validation: verify service account not being used for data source connection credentials

Verifies that credentials that have been used to create Google BigQuery data sources are not the same credentials used to configure the Google BigQuery integration.

"BigQuery doesn't support the reuse of service accounts for integrations that are currently being used for data sources."

Validate manual: [dataset - create]

Verifies that the custom role assigned to the service account has the permissions to create the dataset.

Message includes a permission warning.

Validate manual: [dataset - delete]

Verifies that the custom role assigned to the service account has the permissions to delete the Immuta-managed dataset.

Message includes a permission warning.

Initialize validation: [dataset - exists]

Verifies that this dataset does not already exist.

"An existing Immuta instance exists. Delete this dataset to continue."

Validate manual: [table - create]

Verifies that the custom role assigned to the service account has the permissions to create Immuta-managed tables.

Message includes a permission warning.

Validate manual: [table - delete]

Verifies that the custom role assigned to the service account has the permissions to delete Immuta-managed tables.

Message includes a permission warning.

Validate manual: [table - get]

Verifies that the custom role assigned to the service account has the permissions to get Immuta-managed tables.

Message includes a permission warning.

Validate manual: [table - insert]

Verifies that the custom role assigned to the service account has the permissions to insert rows in Immuta-managed tables.

Message includes a permission warning.

Validate manual: [table - update]

Verifies that the custom role assigned to the service account has the permissions to update Immuta-managed tables.

Message includes a permission warning.

Redshift validation tests

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

Test name
Description
Message

Initial validation: basic connection test

Verifies that Immuta can connect to Redshift.

"Unable to connect to host."

Validate automatic: database does not exist

Verifies that the database specified in the request payload does not already exist.

"The database already exists. If this database can be safely dropped, please do so and try again. Alternatively, specify a different database name."

Validate automatic: impersonation role does not exist

Verifies that the user impersonation role specified in the request payload does not already exist.

"Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name."

Snowflake validation tests

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

Test name
Description
Message

Initial validation: basic connection test

Verifies that Immuta can connect to the Snowflake database.

"Unable to connect to host."

Initial validation: default warehouse access test

Verifies that the default warehouse exists and that the Immuta system account user has permissions to act on the default warehouse specified.

"Unable to access default warehouse. If this was a manual installation, ensure that the user has been granted usage on the specified warehouse."

Initial validation: table grants role prefix is unique

"The Snowflake table grants role prefix IMMUTA is used by another Immuta instance connected to the same Snowflake host. Please update the table grants role prefix for this Immuta instance and try again."

Initial validation: validate access to privileged role

Verifies that the privileged role exists and that it has been assigned to the Immuta system account user.

"User does not have access to the privileged role."

Validate automatic bootstrap user grants

Verifies the credentials of the user executing the Immuta bootstrap script in Snowflake.

-

Validate automatic: database does not exist

Verifies that the database specified in the request payload does not already exist.

"The database already exists. If this database can be safely dropped, please do so and try again. Alternatively, specify a different database name."

Validate automatic: impersonation role does not exist

Verifies that the user impersonation role specified in the request payload does not already exist.

"Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name."

PreviousIntegration Configuration PayloadNextHTTP Status Codes and Error Messages

Last updated 1 month ago

Was this helpful?

The status of the integration. Statuses include createError, creating, deleteError, deleting, editError, editing, enabled, migrateError, and migrating. See the below for descriptions.

The results of the validation tests. See the for details.

The integration configuration. See the integration configuration payload for , , , , , or for details.

Verifies that the prefix for Snowflake table grants does not already exist. If this prefix already exists, navigate to the Integration Settings section on the Immuta app settings page to .

disable Snowflake table grants, re-enable it, and then update the role prefix
status string
statuses table
validationResults object
object description
Azure Synapse Analytics
Databricks Unity Catalog
Google BigQuery
Redshift
Snowflake
Amazon S3
Azure Synapse Analytics
Databricks Unity Catalog
Google BigQuery
Redshift
Snowflake
Amazon S3
Azure Synapse Analytics
Databricks Unity Catalog
Google BigQuery
Redshift
Snowflake