Manage Connection Settings

This page details the /data v1 API options available for connection-level objects.

• For a how-to on registering a connection, see the Register a connection guide.

• For details on the /data v1 API options available for objects within a connection, see the Manage connection objects guide.

These endpoints are only available to connections from the following technologies:

• Snowflake

• Databricks Unity Catalog

• AWS Lake Formation

Method	Endpoint	Description
GET	/data/connection/{connectionKey}	Search for a connection using a connection key
PUT	/data/connection/{connectionKey}	Update the connection information for the specified connection

GET /data/connection/{connectionKey}

Search for a connection using a connection key.

Required Immuta permission: CREATE_DATA_SOURCE, APPLICATION_ADMIN, GOVERNANCE, or data owner within the hierarchy

curl -X 'GET' \
  'https://your-immuta-url.com/data/connection/yourConnectionKey' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-bearer-token'

Path parameters

Attribute	Description	Required
connectionKey string	The key to uniquely identify the connection. This is the same as the display name of the connection in the Immuta UI.	Yes

Response schema

Attribute	Description
connectionKey string	The key to uniquely identify the connection.
connection object	Integration-specific connection information (i.e., hostname, authentication type, warehouse, etc.)
createdAt timestamp	The time the connection was registered in Immuta.
createdBy integer	The ID of the user who registered the connection.
creator.id integer	The ID of the user who registered the connection.
creator.name string	The name of the user who registered the connection.
creator.email string	The email of the user who registered the connection.
updatedAt timestamp	The time the connection was updated in Immuta.
updatedBy integer	The ID of the user who updated the connection.
updater.id integer	The ID of the user who updated the connection.
updater.name string	The name of the user who updated the connection.
updater.email string	The email of the user who updated the connection.
nativeIntegrationId integer	The ID of the integration backing the connection.

Example response

{
  "connectionKey": "yourConnectionKey",
  "connection": {
    "port": 443,
    "role": "IMMUTA_SNOWFLAKE_ROLE",
    "hostname": "example.us-east-1.snowflakecomputing.com",
    "username": "IMMUTA_DB_SYSTEM_ACCOUNT",
    "warehouse": "your-warehouse",
    "technology": "Snowflake",
    "authenticationType": "userPassword"
  },
  "createdAt": "2023-12-22T18:28:46.328Z",
  "createdBy": 2,
  "updatedAt": "2023-12-22T18:28:46.328Z",
  "updatedBy": 2,
  "creator": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "[email protected]"
  },
  "updater": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "[email protected]"
  },
  "nativeIntegrationId": 1
}

PUT /data/connection/{connectionKey}

Update the connection information for the specified connection. Partial updates are not supported.

Required Immuta permission: APPLICATION_ADMIN

What can be updated?

Using this endpoint, you can only update connection information. To update other integration details, use the PUT /integrations/{id} endpoint.

Snowflake username and password

curl -X 'PUT' \
    'https://<your-immuta-url>/data/connection/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     "connection": {
       "technology": "Snowflake",
       "hostname": "<your-Snowflake-hostname-url>",
       "port": <your-Snowflake-port>,
       "warehouse": "<your-Snowflake-warehouse>",
       "role": "<your-Snowflake-role>",
       "authenticationType": "userPassword",
       "username": "<your-Snowflake-username>",
       "password": "<your-Snowflake-password>"
     }
    }'

Snowflake key pair

Snowflake OAuth with certificate

Snowflake OAuth with secret

Databricks Unity Catalog

Path parameters

Attribute	Description	Required
connectionKey string	The key to uniquely identify the connection. This is the same as the display name of the connection in the Immuta UI.	Yes

Body parameters

The connection parameters differ based on your backing technology. See the Connection registration payload reference guide for details about the payloads.

Response schema

Attribute	Description
objectPath string	The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the connectionKey and all names are separated by forward slashes.
bulkId string	A bulk ID that can be used to search for the status of background jobs triggered by this request.

Example response

{
  "objectPath": ['yourConnectionKey'],
  "bulkId": "a-new-uuid"
}