# 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](/saas/developer-guides/api-intro/connections-api/how-to-guides/register-a-connection.md).
* For details on the `/data` v1 API options available for objects within a connection, see the [Manage connection objects guide](/saas/developer-guides/api-intro/connections-api/how-to-guides/manage-a-connection.md).

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

* Snowflake
* Databricks Unity Catalog
* AWS Lake Formation

| Method  | Endpoint                                                                                                  | Description                                                    |
| ------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **GET** | [<mark style="color:blue;">`/data/connection/{connectionKey}`</mark>](#get-data-connection-connectionkey) | Search for a connection using a connection key                 |
| **PUT** | [<mark style="color:blue;">`/data/connection/{connectionKey}`</mark>](#put-data-connection-connectionkey) | Update the connection information for the specified connection |

## <mark style="color:green;">`GET`</mark> `/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

<table><thead><tr><th width="197">Attribute</th><th width="414">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>connectionKey</strong> <code>string</code></td><td>The key to uniquely identify the connection. This is the same as the display name of the connection in the Immuta UI.</td><td><strong>Yes</strong></td></tr></tbody></table>

#### Response schema

<table><thead><tr><th width="197">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>connectionKey</strong> <code>string</code></td><td>The key to uniquely identify the connection.</td></tr><tr><td><strong>connection</strong> <code>object</code></td><td>Integration-specific connection information (i.e., hostname, authentication type, warehouse, etc.)</td></tr><tr><td><strong>createdAt</strong> <code>timestamp</code></td><td>The time the connection was registered in Immuta.</td></tr><tr><td><strong>createdBy</strong> <code>integer</code></td><td>The ID of the user who registered the connection.</td></tr><tr><td>creator.<strong>id</strong> <code>integer</code></td><td>The ID of the user who registered the connection.</td></tr><tr><td>creator.<strong>name</strong> <code>string</code></td><td>The name of the user who registered the connection.</td></tr><tr><td>creator.<strong>email</strong> <code>string</code></td><td>The email of the user who registered the connection.</td></tr><tr><td><strong>updatedAt</strong> <code>timestamp</code></td><td>The time the connection was updated in Immuta.</td></tr><tr><td><strong>updatedBy</strong> <code>integer</code></td><td>The ID of the user who updated the connection.</td></tr><tr><td>updater.<strong>id</strong> <code>integer</code></td><td>The ID of the user who updated the connection.</td></tr><tr><td>updater.<strong>name</strong> <code>string</code></td><td>The name of the user who updated the connection.</td></tr><tr><td>updater.<strong>email</strong> <code>string</code></td><td>The email of the user who updated the connection.</td></tr><tr><td><strong>nativeIntegrationId</strong> <code>integer</code></td><td>The ID of the integration backing the connection.</td></tr></tbody></table>

#### 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": "taylor@immuta.com"
  },
  "updater": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "taylor@immuta.com"
  },
  "nativeIntegrationId": 1
}
```

## <mark style="color:green;">`PUT`</mark> `/data/connection/{connectionKey}`

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

**Required Immuta permission**: `APPLICATION_ADMIN`

{% hint style="warning" %}
**What can be updated?**

Using this endpoint, you can only update connection information. To update other integration details, use the [<mark style="color:blue;">PUT</mark> <mark style="color:blue;">`/integrations/{id}`</mark>](/saas/developer-guides/api-intro/integrations-api/reference-guides/integrations-api.md#put-integrations-id) endpoint.
{% endhint %}

{% tabs %}
{% tab title="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>"
     }
    }'
```

{% endtab %}

{% tab title="Snowflake key pair" %}

```
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": "keyPair",
       "username": "<the-Snowflake-username>",
       "privateKeyPassword": "<your-Snowflake-key-password>",
       "privateKey": {
         "keyName": "PRIV_KEY_FILE",
         "userFilename": "<your-private-key-file-name>",
         "content": "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->"
       }
     }
    }'
```

{% endtab %}

{% tab title="Snowflake OAuth with certificate" %}

```
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": "oAuthClientCredentials",
       "oAuthClientConfig": {
         "useCertificate": true,
         "clientId": "<your-client-ID>",
         "authorityUrl": "<your-example.authority.com>",
         "scope": "session:role-any",
         "publicCertificateThumbprint": "<your-certificate-thumbprint>",
         "resource": "<your-optional-resource>",
         "oauthPrivateKey": {
           "keyName": "oauth client certificate",
           "userFilename": "<your-user-file.pem>",
           "content": "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->"
         }
       }
     }
    }'
```

{% endtab %}

{% tab title="Snowflake OAuth with secret" %}

```
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": "oAuthClientCredentials",
       "oAuthClientConfig": {
         "useCertificate": false,
         "clientId": "<your-client-ID>",
         "authorityUrl": "<your-example.authority.com>",
         "scope": "session:role-any",
         "resource": "<your-optional-resource>",
         "clientSecret": "<your-client-secret>"
       }
     }
    }'
```

{% endtab %}

{% tab title="Databricks Unity Catalog" %}

```
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": "Databricks",
       "hostname": "<www.your-workspace.cloud.databricks.com>",
       "port": <your-Databricks-port>,
       "httpPath": "<your-Databricks-warehouse-path>",
       "authenticationType": "token",
       "token": "<your-service-principal-pat>"
     }
    }'
```

{% endtab %}
{% endtabs %}

#### 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](/saas/developer-guides/api-intro/connections-api/connection-registration-payloads-reference-guide.md) for details about the payloads.

#### Response schema

<table><thead><tr><th width="147">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>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 <code>connectionKey</code> and all names are separated by forward slashes.</td></tr><tr><td><strong>bulkId</strong> <code>string</code></td><td>A bulk ID that can be used to search for the status of background jobs triggered by this request.</td></tr></tbody></table>

#### Example response

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/connections-api/how-to-guides/manage-connection-settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.