> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connections

A connection is your environment's settings for one connector, such as Gmail: its name and the OAuth client ID, client secret and scopes Scalekit uses to sign users in to the app. Users then link their own accounts to it as connected accounts. See [Connections](https://docs.scalekit.com/agentkit/connections/) for setting one up in the dashboard.

**Typical flow.** [Create a connection](https://docs.scalekit.com/agentkit/reference/connections/create-a-connection/) for a connector, register an OAuth app with the provider using the `redirect_uri` in the response, then [update the connection](https://docs.scalekit.com/agentkit/reference/connections/update-a-connection/) with the app's client ID, client secret and the scopes you need.

One page per endpoint, each with its own markdown copy:

| Endpoint | Request | What it does | Python SDK | Node.js SDK |
| --- | --- | --- | --- | --- |
| [Create a connection](https://docs.scalekit.com/agentkit/reference/connections/create-a-connection.md) | `POST /api/v1/agentkit/connection` | Create a connection for a connector, such as Gmail. | `actions.create_connection` | `actions.createConnection` |
| [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection.md) | `GET /api/v1/agentkit/connection/{connection_identifier}` | Get a connection and its settings, by the connection's name or ID. | `actions.get_connection` | `actions.getConnection` |
| [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections.md) | `GET /api/v1/agentkit/connection` | List connections, filtered by connector or name. | `actions.list_app_connections` | `actions.listAppConnections` |
| [Update a connection](https://docs.scalekit.com/agentkit/reference/connections/update-a-connection.md) | `PATCH /api/v1/agentkit/connection/{connection_id}` | Rename a connection, or change its client ID, client secret and scopes. | `actions.update_connection` | `actions.updateConnection` |
| [Delete a connection](https://docs.scalekit.com/agentkit/reference/connections/delete-a-connection.md) | `DELETE /api/v1/connections/{connection_id}` | Delete a connection. | `actions.delete_connection` | `actions.deleteConnection` |


## Create a connection

`POST /api/v1/agentkit/connection`

Creates a connection for a connector, such as Gmail. The connection's type comes from the connector, and an OAuth connection starts with the connector's endpoints and default scopes. Next, register an OAuth app with the provider using the `redirect_uri` from the response, then add its client ID, client secret and the scopes you need with [Update a connection](https://docs.scalekit.com/agentkit/reference/connections/update-a-connection/).

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | Yes | The connector's identifier, such as `GMAIL`. To find a connector's identifier, call [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors) and read `identifier`. |
| `auth_mode` | string (enum) | No | `USER` (default): each user authorizes their own account. `ORG_WIDE`: one admin authorizes an account that every user shares. You can't change it after the connection is created. One of: `USER`, `ORG_WIDE`. |
| `connection_name` | string | No | A name for the connection, such as `gmail-work`: letters, numbers and hyphens, unique in the environment. Your code passes this name as `connection_name` when it creates connected accounts and runs tools. Scalekit generates one if you leave it out. |
| `provider_configurations` | object | No | Extra settings, only for the connectors named on each field, such as `provider_domain` for a connector with regional domains. |
| `provider_configurations.googleads_developer_token` | string | No | Google Ads only: your Google Ads API developer token. See Google's [Obtain a developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token). Responses show it masked. |
| `provider_configurations.microsoft_tenant_id` | string | No | Microsoft connectors only: the ID of your Microsoft Entra tenant, from the **Overview** page of Microsoft Entra ID in the Azure portal. |
| `provider_configurations.provider_domain` | string | No | The regional domain that hosts your account, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region, for connectors that need one. Set it when you create the connection; it can't be changed later and isn't returned. |
| `provider_configurations.slack_connection_type` | string (enum) | No | Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects. One of: `BOT`, `USER`. |
| `provider_configurations.smart_fhir_aud` | string | No | SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in. |
| `provider_configurations.smart_fhir_domain` | string | No | SMART on FHIR only: the domain of the FHIR server. |
| `provider_configurations.trello_app_name` | string | No | Trello only: the name of your Trello app, which Trello shows users when they authorize it. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connection` | object | The connection that was created. |
| `connection.auth_mode` | string (enum) | `USER`: each user authorizes their own account. `ORG_WIDE`: one admin-authorized account is shared. One of: `USER`, `ORG_WIDE`. |
| `connection.connection_mcp_url` | string | The URL of an MCP server that Scalekit hosts for this connection alone. Empty when the connection has none. |
| `connection.connection_name` | string | The connection's name, such as `gmail-work`. Your code passes this name as `connection_name` when it creates connected accounts and runs tools. |
| `connection.create_time` | string | When the connection was created. |
| `connection.google_dwd_config` | object | Google domain-wide delegation settings. Present only for `GOOGLE_DWD` connections. |
| `connection.google_dwd_config.required_scopes` | array of string | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `scopes`. |
| `connection.google_dwd_config.scope_selection_allowed` | boolean | Set to `true` to let users choose which of the `scopes` to grant when they connect. |
| `connection.google_dwd_config.scopes` | array of string | The Google scopes to request, such as `https://www.googleapis.com/auth/gmail.readonly`. A list you send replaces the current one. Authorize the same scopes for the service account's client ID in the Google Workspace Admin console, under **Security** > **Access and data control** > **API controls** > **Manage domain wide delegation**. |
| `connection.google_dwd_config.service_account_json` | string | The contents of the service account's JSON key file, as a string. Create the key in the Google Cloud console under **IAM & Admin** > **Service accounts** > your service account > **Keys** > **Add key**. Responses show it masked. |
| `connection.google_dwd_config.token_uri` | string | Google's token URL. Leave it out to use `https://oauth2.googleapis.com/token`. |
| `connection.id` | string | The connection's ID. |
| `connection.oauth_config` | object | OAuth settings. Present for connections that use OAuth. |
| `connection.oauth_config.access_type` | string | The `access_type` value sent to the provider, such as `offline`. |
| `connection.oauth_config.authorize_uri` | string | The provider's authorization URL. |
| `connection.oauth_config.client_id` | string | The client ID of the OAuth app you registered with the provider, such as `123456789012-abc123def456.apps.googleusercontent.com` for a Google app. Get it from the provider's developer console when you create the app (for Gmail: Google Cloud console, **APIs & Services** > **Credentials**, an OAuth client ID of type web application), and add this connection's `redirect_uri` to the app as an authorized redirect URI. Each connector's page under [Connectors](https://docs.scalekit.com/agentkit/connectors/) has the steps for that provider. |
| `connection.oauth_config.client_secret` | string | The client secret of the same OAuth app, from the provider's developer console. Write-only: responses show it masked, such as `********abcd`. Leave it out to keep the stored secret. |
| `connection.oauth_config.extra_authorize_params` | object | Extra query parameters to add to the provider's authorization URL, as name-value pairs, such as `{"hd": "example.com"}`, which asks Google to suggest accounts from that domain. Check the provider's OAuth documentation for the parameters it accepts. Send `{}` to clear them. |
| `connection.oauth_config.optional_scopes` | object | A second set of scopes, for providers that take them in a separate authorization parameter, such as Slack's `user_scope`. Set `field_name` to that parameter's name and `scopes` to its values. |
| `connection.oauth_config.pkce_enabled` | boolean | Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE. |
| `connection.oauth_config.prompt` | string | The `prompt` value sent to the provider, which controls whether the user signs in or consents again, such as `consent`. Send an empty string to send no `prompt`. |
| `connection.oauth_config.redirect_uri` | string | The redirect URI to add to the app you registered with the provider, as an authorized redirect URI. Scalekit sets it; you can't change it. |
| `connection.oauth_config.required_optional_scopes` | array of string | Scopes from `optional_scopes.scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `optional_scopes.scopes`. |
| `connection.oauth_config.required_scopes` | array of string | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`, such as the read scope your tools always need. Each must also be in `scopes`, or the request fails with `400`. |
| `connection.oauth_config.scope_selection_allowed` | boolean | Set to `true` to let users choose which of the `scopes` to grant when they connect. Scopes in `required_scopes` stay selected. |
| `connection.oauth_config.scopes` | array of string | The OAuth scopes users grant when they connect, such as `https://www.googleapis.com/auth/gmail.readonly` for Gmail. A list you send replaces the whole current list, so include the scopes you want to keep. To build it, start from the current scopes in [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/), then pick from the scopes the connector offers: call [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors) with `identifier` set to the connector, such as `GMAIL`, and read `auth_patterns[].oauth_config.available_scopes[].scope`. You can also add a scope that isn't listed there, using the exact scope string from the provider's own documentation, such as Google's [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes). |
| `connection.oauth_config.token_access_type` | string | The `token_access_type` value sent to the provider, for providers that use it, such as Dropbox with `offline`. |
| `connection.oauth_config.token_endpoint_auth_method` | string (enum) | How Scalekit sends client credentials to the provider's token URL. `DEFAULT` lets Scalekit choose. One of: `NONE`, `BASIC_AUTH`, `REQUEST_BODY`, `DEFAULT`. |
| `connection.oauth_config.token_uri` | string | The provider's token URL. |
| `connection.oauth_config.use_scalekit_creds` | boolean | Set to `true` to use Scalekit's own OAuth app instead of yours, for connectors that offer one; otherwise the request fails with `400`. Sending your own `client_id` or `client_secret` sets it to `false` unless you also send it. |
| `connection.oauth_config.user_info_uri` | string | The provider's user info URL. |
| `connection.provider` | string | The connector this connection uses, such as `GMAIL`. |
| `connection.provider_configurations` | object | Settings for connectors that need extra ones, such as Slack. |
| `connection.provider_configurations.googleads_developer_token` | string | Google Ads only: your Google Ads API developer token. See Google's [Obtain a developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token). Responses show it masked. |
| `connection.provider_configurations.microsoft_tenant_id` | string | Microsoft connectors only: the ID of your Microsoft Entra tenant, from the **Overview** page of Microsoft Entra ID in the Azure portal. |
| `connection.provider_configurations.provider_domain` | string | The regional domain that hosts your account, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region, for connectors that need one. Set it when you create the connection; it can't be changed later and isn't returned. |
| `connection.provider_configurations.slack_connection_type` | string (enum) | Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects. One of: `BOT`, `USER`. |
| `connection.provider_configurations.smart_fhir_aud` | string | SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in. |
| `connection.provider_configurations.smart_fhir_domain` | string | SMART on FHIR only: the domain of the FHIR server. |
| `connection.provider_configurations.trello_app_name` | string | Trello only: the name of your Trello app, which Trello shows users when they authorize it. |
| `connection.type` | string (enum) | How users authenticate to the app, such as `OAUTH`. It comes from the connector and decides which settings object applies (`oauth_config` or `google_dwd_config`). One of: `OIDC`, `SAML`, `PASSWORD`, `OAUTH`, `PASSWORDLESS`, `BASIC`, `BEARER`, `API_KEY`, `WEBAUTHN`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connection.update_time` | string | When the connection was last changed. |

**Errors**

- `400`: Invalid request - the connector is missing or unknown, or the connection name is already used or reserved. Error code `DUPLICATE_IDENTIFIER` when the name is already used.
- `401`: Authentication required - missing or invalid access token

**Request**

```bash
curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/agentkit/connection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "GMAIL",
    "connection_name": "gmail-work"
  }'
```

**Response**

```json
{
  "connection": {
    "id": "conn_70219645518265104",
    "type": "OAUTH",
    "create_time": "2026-10-02T14:30:00Z",
    "update_time": "2026-10-02T14:30:00Z",
    "provider": "GMAIL",
    "connection_name": "gmail-work",
    "auth_mode": "USER",
    "oauth_config": {
      "authorize_uri": "https://accounts.google.com/o/oauth2/v2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "user_info_uri": "https://www.googleapis.com/oauth2/v2/userinfo",
      "client_id": "",
      "client_secret": "",
      "scopes": [
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/gmail.modify",
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/contacts.readonly",
        "https://www.googleapis.com/auth/contacts.other.readonly",
        "https://www.googleapis.com/auth/gmail.settings.basic"
      ],
      "redirect_uri": "https://your-env.scalekit.dev/sso/v1/oauth/conn_70219645518265104/callback",
      "pkce_enabled": false,
      "use_scalekit_creds": false,
      "extra_authorize_params": {},
      "token_endpoint_auth_method": "DEFAULT",
      "scope_selection_allowed": false,
      "required_scopes": [],
      "required_optional_scopes": []
    }
  }
}
```

**Python SDK:** `scalekit_client.actions.create_connection`

Creates a connection for a connector, such as `GMAIL`. Then set its credentials and scopes with `update_connection`.

```python
scalekit_client.actions.create_connection(
    provider: str,
    connection_name: Optional[str] = None,
    auth_mode: Optional[AuthMode] = None,
    provider_domain: Optional[str] = None,
) -> AgentKitConnection
```

Example:

```python
result = scalekit_client.actions.create_connection(
    provider="GMAIL",
    connection_name="gmail-work",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | `str` | Yes | The connector's identifier, such as `GMAIL`. To find it, call [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors) and read `identifier`. |
| `connection_name` | `Optional[str]` | No | A name for the connection, such as `gmail-work`: letters, numbers and hyphens, unique in the environment. Your code passes this name when it creates connected accounts and runs tools. Scalekit generates one if you leave it out. |
| `auth_mode` | `Optional[AuthMode]` | No | `AuthMode.USER` (default): each user authorizes their own account. `AuthMode.ORG_WIDE`: one admin authorizes an account that every user shares. Import it with `from scalekit.actions.connections import AuthMode`. You can't change it later. |
| `provider_domain` | `Optional[str]` | No | The regional domain, for connectors that need one, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region. You can't change it later. |

Returns `AgentKitConnection`: The created connection.

**Node.js SDK:** `scalekit.actions.createConnection`

Creates a connection for a connector, such as `GMAIL`. Then set its credentials and scopes with `updateConnection`.

```ts
scalekit.actions.createConnection(
  params: {
    provider: string;
    connectionName?: string;
    authMode?: AgentKitAuthMode;
    providerDomain?: string;
  },
): Promise<AgentKitConnection>
```

Example:

```ts
const result = await scalekit.actions.createConnection({
  provider: "GMAIL",
  connectionName: "gmail-work",
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | `string` | Yes | The connector's identifier, such as `GMAIL`. To find it, call [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors) and read `identifier`. |
| `connectionName` | `string` | No | A name for the connection, such as `gmail-work`: letters, numbers and hyphens, unique in the environment. Your code passes this name when it creates connected accounts and runs tools. Scalekit generates one if you leave it out. |
| `authMode` | `AgentKitAuthMode` | No | `'USER'` (default): each user authorizes their own account. `'ORG_WIDE'`: one admin authorizes an account that every user shares. You can't change it later. |
| `providerDomain` | `string` | No | The regional domain, for connectors that need one, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region. You can't change it later. |

Returns `Promise<AgentKitConnection>`: The created connection.

**Used in**

- [Set up a connection](https://docs.scalekit.com/agentkit/connections/)

## Get a connection

`GET /api/v1/agentkit/connection/{connection_identifier}`

Returns a connection with its settings, looked up by its name or its ID. Use it to check the scopes the connection requests, or to copy its `redirect_uri` into the app you registered with the provider. Secrets come back masked.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_identifier` | string | Yes | The connection's name, such as `gmail-work`, or its ID, such as `conn_70219645518265104`. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connection` | object | The connection. |
| `connection.auth_mode` | string (enum) | `USER`: each user authorizes their own account. `ORG_WIDE`: one admin-authorized account is shared. One of: `USER`, `ORG_WIDE`. |
| `connection.connection_mcp_url` | string | The URL of an MCP server that Scalekit hosts for this connection alone. Empty when the connection has none. |
| `connection.connection_name` | string | The connection's name, such as `gmail-work`. Your code passes this name as `connection_name` when it creates connected accounts and runs tools. |
| `connection.create_time` | string | When the connection was created. |
| `connection.google_dwd_config` | object | Google domain-wide delegation settings. Present only for `GOOGLE_DWD` connections. |
| `connection.google_dwd_config.required_scopes` | array of string | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `scopes`. |
| `connection.google_dwd_config.scope_selection_allowed` | boolean | Set to `true` to let users choose which of the `scopes` to grant when they connect. |
| `connection.google_dwd_config.scopes` | array of string | The Google scopes to request, such as `https://www.googleapis.com/auth/gmail.readonly`. A list you send replaces the current one. Authorize the same scopes for the service account's client ID in the Google Workspace Admin console, under **Security** > **Access and data control** > **API controls** > **Manage domain wide delegation**. |
| `connection.google_dwd_config.service_account_json` | string | The contents of the service account's JSON key file, as a string. Create the key in the Google Cloud console under **IAM & Admin** > **Service accounts** > your service account > **Keys** > **Add key**. Responses show it masked. |
| `connection.google_dwd_config.token_uri` | string | Google's token URL. Leave it out to use `https://oauth2.googleapis.com/token`. |
| `connection.id` | string | The connection's ID. |
| `connection.oauth_config` | object | OAuth settings. Present for connections that use OAuth. |
| `connection.oauth_config.access_type` | string | The `access_type` value sent to the provider, such as `offline`. |
| `connection.oauth_config.authorize_uri` | string | The provider's authorization URL. |
| `connection.oauth_config.client_id` | string | The client ID of the OAuth app you registered with the provider, such as `123456789012-abc123def456.apps.googleusercontent.com` for a Google app. Get it from the provider's developer console when you create the app (for Gmail: Google Cloud console, **APIs & Services** > **Credentials**, an OAuth client ID of type web application), and add this connection's `redirect_uri` to the app as an authorized redirect URI. Each connector's page under [Connectors](https://docs.scalekit.com/agentkit/connectors/) has the steps for that provider. |
| `connection.oauth_config.client_secret` | string | The client secret of the same OAuth app, from the provider's developer console. Write-only: responses show it masked, such as `********abcd`. Leave it out to keep the stored secret. |
| `connection.oauth_config.extra_authorize_params` | object | Extra query parameters to add to the provider's authorization URL, as name-value pairs, such as `{"hd": "example.com"}`, which asks Google to suggest accounts from that domain. Check the provider's OAuth documentation for the parameters it accepts. Send `{}` to clear them. |
| `connection.oauth_config.optional_scopes` | object | A second set of scopes, for providers that take them in a separate authorization parameter, such as Slack's `user_scope`. Set `field_name` to that parameter's name and `scopes` to its values. |
| `connection.oauth_config.pkce_enabled` | boolean | Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE. |
| `connection.oauth_config.prompt` | string | The `prompt` value sent to the provider, which controls whether the user signs in or consents again, such as `consent`. Send an empty string to send no `prompt`. |
| `connection.oauth_config.redirect_uri` | string | The redirect URI to add to the app you registered with the provider, as an authorized redirect URI. Scalekit sets it; you can't change it. |
| `connection.oauth_config.required_optional_scopes` | array of string | Scopes from `optional_scopes.scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `optional_scopes.scopes`. |
| `connection.oauth_config.required_scopes` | array of string | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`, such as the read scope your tools always need. Each must also be in `scopes`, or the request fails with `400`. |
| `connection.oauth_config.scope_selection_allowed` | boolean | Set to `true` to let users choose which of the `scopes` to grant when they connect. Scopes in `required_scopes` stay selected. |
| `connection.oauth_config.scopes` | array of string | The OAuth scopes users grant when they connect, such as `https://www.googleapis.com/auth/gmail.readonly` for Gmail. A list you send replaces the whole current list, so include the scopes you want to keep. To build it, start from the current scopes in [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/), then pick from the scopes the connector offers: call [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors) with `identifier` set to the connector, such as `GMAIL`, and read `auth_patterns[].oauth_config.available_scopes[].scope`. You can also add a scope that isn't listed there, using the exact scope string from the provider's own documentation, such as Google's [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes). |
| `connection.oauth_config.token_access_type` | string | The `token_access_type` value sent to the provider, for providers that use it, such as Dropbox with `offline`. |
| `connection.oauth_config.token_endpoint_auth_method` | string (enum) | How Scalekit sends client credentials to the provider's token URL. `DEFAULT` lets Scalekit choose. One of: `NONE`, `BASIC_AUTH`, `REQUEST_BODY`, `DEFAULT`. |
| `connection.oauth_config.token_uri` | string | The provider's token URL. |
| `connection.oauth_config.use_scalekit_creds` | boolean | Set to `true` to use Scalekit's own OAuth app instead of yours, for connectors that offer one; otherwise the request fails with `400`. Sending your own `client_id` or `client_secret` sets it to `false` unless you also send it. |
| `connection.oauth_config.user_info_uri` | string | The provider's user info URL. |
| `connection.provider` | string | The connector this connection uses, such as `GMAIL`. |
| `connection.provider_configurations` | object | Settings for connectors that need extra ones, such as Slack. |
| `connection.provider_configurations.googleads_developer_token` | string | Google Ads only: your Google Ads API developer token. See Google's [Obtain a developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token). Responses show it masked. |
| `connection.provider_configurations.microsoft_tenant_id` | string | Microsoft connectors only: the ID of your Microsoft Entra tenant, from the **Overview** page of Microsoft Entra ID in the Azure portal. |
| `connection.provider_configurations.provider_domain` | string | The regional domain that hosts your account, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region, for connectors that need one. Set it when you create the connection; it can't be changed later and isn't returned. |
| `connection.provider_configurations.slack_connection_type` | string (enum) | Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects. One of: `BOT`, `USER`. |
| `connection.provider_configurations.smart_fhir_aud` | string | SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in. |
| `connection.provider_configurations.smart_fhir_domain` | string | SMART on FHIR only: the domain of the FHIR server. |
| `connection.provider_configurations.trello_app_name` | string | Trello only: the name of your Trello app, which Trello shows users when they authorize it. |
| `connection.type` | string (enum) | How users authenticate to the app, such as `OAUTH`. It comes from the connector and decides which settings object applies (`oauth_config` or `google_dwd_config`). One of: `OIDC`, `SAML`, `PASSWORD`, `OAUTH`, `PASSWORDLESS`, `BASIC`, `BEARER`, `API_KEY`, `WEBAUTHN`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connection.update_time` | string | When the connection was last changed. |

**Errors**

- `401`: Authentication required - missing or invalid access token
- `404`: Not found - no connection with this name or ID. Error code `RESOURCE_NOT_FOUND`.

**Request**

```bash
curl -sS -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/agentkit/connection/gmail-work" \
  -H "Authorization: Bearer $TOKEN"
```

**Response**

```json
{
  "connection": {
    "id": "conn_70219645518265104",
    "type": "OAUTH",
    "create_time": "2026-10-02T14:30:00Z",
    "update_time": "2026-10-02T14:30:00Z",
    "provider": "GMAIL",
    "connection_name": "gmail-work",
    "auth_mode": "USER",
    "oauth_config": {
      "authorize_uri": "https://accounts.google.com/o/oauth2/v2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "user_info_uri": "https://www.googleapis.com/oauth2/v2/userinfo",
      "client_id": "",
      "client_secret": "",
      "scopes": [
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/gmail.modify",
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/contacts.readonly",
        "https://www.googleapis.com/auth/contacts.other.readonly",
        "https://www.googleapis.com/auth/gmail.settings.basic"
      ],
      "redirect_uri": "https://your-env.scalekit.dev/sso/v1/oauth/conn_70219645518265104/callback",
      "pkce_enabled": false,
      "use_scalekit_creds": false,
      "extra_authorize_params": {},
      "token_endpoint_auth_method": "DEFAULT",
      "scope_selection_allowed": false,
      "required_scopes": [],
      "required_optional_scopes": []
    },
    "connection_mcp_url": "https://your-env.scalekit.dev/mcp/v3/connections/gmail-work"
  }
}
```

**Python SDK:** `scalekit_client.actions.get_connection`

Gets a connection by name or ID. Pass the connection's name, or its ID with `connection_id`.

```python
scalekit_client.actions.get_connection(
    connection_name: Optional[str] = None,
    connection_id: Optional[str] = None,
) -> AgentKitConnection
```

Example:

```python
result = scalekit_client.actions.get_connection(
    connection_name="gmail-work",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection's name, such as `gmail-work`. |
| `connection_id` | `Optional[str]` | No | The connection's ID, such as `conn_70219645518265104`, instead of its name. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

Returns `AgentKitConnection`.

**Node.js SDK:** `scalekit.actions.getConnection`

Gets a connection by name or ID. Pass the connection's name or ID.

```ts
scalekit.actions.getConnection(
  connection: string | ConnectionRef,
): Promise<AgentKitConnection>
```

Example:

```ts
const result = await scalekit.actions.getConnection("gmail-work");
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection` | `string \| ConnectionRef` | Yes | The connection's name, such as `gmail-work`, or its ID, such as `conn_70219645518265104`, as a string, or `{ connectionName }` or `{ connectionId }`. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

Returns `Promise<AgentKitConnection>`.

**Used in**

- [Set up a connection](https://docs.scalekit.com/agentkit/connections/)

## List connections

`GET /api/v1/agentkit/connection`

Lists the connections in the environment, newest first, without their settings. Filter by connector, or search by name. Use it to find a connection's name or ID, or to check whether a connector already has a connection; call [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/) for one connection's settings.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page_size` | integer | No | The number of connections to return, up to 100. Defaults to 10. |
| `page_token` | string | No | The `next_page_token` from the previous response, to get the next page. Leave it out for the first page. |
| `provider` | string | No | Return only connections for this connector, by its identifier, such as `GMAIL`. A connection's `provider` field holds the same value. |
| `query` | string | No | Return connections whose name, connector or connector display name contains this text, such as `gmail`. At least 3 characters. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connections` | array of object | The connections on this page, newest first. |
| `connections.auth_mode` | string (enum) | `USER`: each user authorizes their own account. `ORG_WIDE`: one admin-authorized account is shared. One of: `USER`, `ORG_WIDE`. |
| `connections.connection_name` | string | The connection's name. |
| `connections.create_time` | string | When the connection was created. |
| `connections.id` | string | The connection's ID. |
| `connections.provider` | string | The connector this connection uses, such as `GMAIL`. |
| `connections.type` | string (enum) | How users authenticate to the app, such as `OAUTH`. One of: `OIDC`, `SAML`, `PASSWORD`, `OAUTH`, `PASSWORDLESS`, `BASIC`, `BEARER`, `API_KEY`, `WEBAUTHN`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `next_page_token` | string | Pass as `page_token` to get the next page. Empty on the last page. |
| `prev_page_token` | string | Pass as `page_token` to get the previous page. |
| `total_size` | integer | The number of connections that match. |

**Errors**

- `400`: Invalid request - for example, `query` is shorter than 3 characters.
- `401`: Authentication required - missing or invalid access token

**Request**

```bash
curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/agentkit/connection" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "provider=GMAIL" \
  --data-urlencode "page_size=10"
```

**Response**

```json
{
  "connections": [
    {
      "id": "conn_70219645518265104",
      "connection_name": "gmail-work",
      "provider": "GMAIL",
      "type": "OAUTH",
      "auth_mode": "USER",
      "create_time": "2026-10-02T14:30:00Z"
    },
    {
      "id": "conn_70219645518265377",
      "connection_name": "gmail-support",
      "provider": "GMAIL",
      "type": "OAUTH",
      "auth_mode": "USER",
      "create_time": "2026-09-28T09:12:00Z"
    }
  ],
  "next_page_token": "",
  "prev_page_token": "",
  "total_size": 2
}
```

**Python SDK:** `scalekit_client.actions.list_app_connections`

Lists connections, newest first. Filter by connector with `provider`, or search by name with `query`.

```python
scalekit_client.actions.list_app_connections(
    provider: Optional[str] = None,
    query: Optional[str] = None,
    page_size: Optional[int] = None,
    page_token: Optional[str] = None,
) -> AgentKitConnectionList
```

Example:

```python
result = scalekit_client.actions.list_app_connections(
    provider="GMAIL",
    page_size=10,
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | `Optional[str]` | No | Return only connections for this connector, by its identifier, such as `GMAIL`. A connection's `provider` field holds the same value. |
| `query` | `Optional[str]` | No | Return connections whose name, connector or connector display name contains this text, such as `gmail`. At least 3 characters. |
| `page_size` | `Optional[int]` | No | The number of connections to return, up to 100. Defaults to 10. |
| `page_token` | `Optional[str]` | No | The `next_page_token` from the previous response, to get the next page. Leave it out for the first page. |

Returns `AgentKitConnectionList`.

**Node.js SDK:** `scalekit.actions.listAppConnections`

Lists connections, newest first. Filter by connector with `provider`, or search by name with `query`.

```ts
scalekit.actions.listAppConnections(
  params?: {
    provider?: string;
    query?: string;
    pageSize?: number;
    pageToken?: string;
  },
): Promise<ListAppConnectionsResponse>
```

Example:

```ts
const result = await scalekit.actions.listAppConnections({
  provider: "GMAIL",
  pageSize: 10,
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | `string` | No | Return only connections for this connector, by its identifier, such as `GMAIL`. A connection's `provider` field holds the same value. |
| `query` | `string` | No | Return connections whose name, connector or connector display name contains this text, such as `gmail`. At least 3 characters. |
| `pageSize` | `number` | No | The number of connections to return, up to 100. Defaults to 10. |
| `pageToken` | `string` | No | The `nextPageToken` from the previous response, to get the next page. Leave it out for the first page. |

Returns `Promise<ListAppConnectionsResponse>`.

## Update a connection

`PATCH /api/v1/agentkit/connection/{connection_id}`

Changes a connection's name or settings. Send only the fields you want to change; everything else keeps its current value, including the stored client secret. To clear a list or a map, send it empty (`[]` or `{}`). To see the current settings first, call [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/). Sending your own `client_id` or `client_secret` switches the connection to your credentials, unless you also set `use_scalekit_creds`.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_id` | string | Yes | The connection's ID, such as `conn_70219645518265104`. Use the ID, not the name. Find it in the `id` field of the [Create](https://docs.scalekit.com/agentkit/reference/connections/create-a-connection/), [Get](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/) or [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | string | No | A new name for the connection, such as `gmail-prod`: letters, numbers and hyphens, unique in the environment. Your code refers to the connection by this name, so update the `connection_name` it passes when you rename one. |
| `google_dwd_config` | object | No | Google domain-wide delegation settings to change. Only for connections whose `type` is `GOOGLE_DWD`. |
| `google_dwd_config.required_scopes` | array of string | No | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `scopes`. |
| `google_dwd_config.scope_selection_allowed` | boolean | No | Set to `true` to let users choose which of the `scopes` to grant when they connect. |
| `google_dwd_config.scopes` | array of string | No | The Google scopes to request, such as `https://www.googleapis.com/auth/gmail.readonly`. A list you send replaces the current one. Authorize the same scopes for the service account's client ID in the Google Workspace Admin console, under **Security** > **Access and data control** > **API controls** > **Manage domain wide delegation**. |
| `google_dwd_config.service_account_json` | string | No | The contents of the service account's JSON key file, as a string. Create the key in the Google Cloud console under **IAM & Admin** > **Service accounts** > your service account > **Keys** > **Add key**. Responses show it masked. |
| `google_dwd_config.token_uri` | string | No | Google's token URL. Leave it out to use `https://oauth2.googleapis.com/token`. |
| `oauth_config` | object | No | OAuth settings to change, such as `client_id`, `client_secret` and `scopes`. For connections that use OAuth, such as `type` `OAUTH`. |
| `oauth_config.access_type` | string | No | The `access_type` value sent to the provider, such as `offline`. |
| `oauth_config.authorize_uri` | string | No | The provider's authorization URL. |
| `oauth_config.client_id` | string | No | The client ID of the OAuth app you registered with the provider, such as `123456789012-abc123def456.apps.googleusercontent.com` for a Google app. Get it from the provider's developer console when you create the app (for Gmail: Google Cloud console, **APIs & Services** > **Credentials**, an OAuth client ID of type web application), and add this connection's `redirect_uri` to the app as an authorized redirect URI. Each connector's page under [Connectors](https://docs.scalekit.com/agentkit/connectors/) has the steps for that provider. |
| `oauth_config.client_secret` | string | No | The client secret of the same OAuth app, from the provider's developer console. Write-only: responses show it masked, such as `********abcd`. Leave it out to keep the stored secret. |
| `oauth_config.extra_authorize_params` | object | No | Extra query parameters to add to the provider's authorization URL, as name-value pairs, such as `{"hd": "example.com"}`, which asks Google to suggest accounts from that domain. Check the provider's OAuth documentation for the parameters it accepts. Send `{}` to clear them. |
| `oauth_config.optional_scopes` | object | No | A second set of scopes, for providers that take them in a separate authorization parameter, such as Slack's `user_scope`. Set `field_name` to that parameter's name and `scopes` to its values. |
| `oauth_config.optional_scopes.field_name` | string | No | Name of the field in which scope should be sent in the authentication request. This is required by some identity providers that expect scopes to be sent in a custom field instead of the standard 'scope' parameter. |
| `oauth_config.optional_scopes.scopes` | array of string | No | List of optional scopes that can be requested during authentication. |
| `oauth_config.pkce_enabled` | boolean | No | Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE. |
| `oauth_config.prompt` | string | No | The `prompt` value sent to the provider, which controls whether the user signs in or consents again, such as `consent`. Send an empty string to send no `prompt`. |
| `oauth_config.redirect_uri` | string | No | The redirect URI to add to the app you registered with the provider, as an authorized redirect URI. Scalekit sets it; you can't change it. |
| `oauth_config.required_optional_scopes` | array of string | No | Scopes from `optional_scopes.scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `optional_scopes.scopes`. |
| `oauth_config.required_scopes` | array of string | No | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`, such as the read scope your tools always need. Each must also be in `scopes`, or the request fails with `400`. |
| `oauth_config.scope_selection_allowed` | boolean | No | Set to `true` to let users choose which of the `scopes` to grant when they connect. Scopes in `required_scopes` stay selected. |
| `oauth_config.scopes` | array of string | No | The OAuth scopes users grant when they connect, such as `https://www.googleapis.com/auth/gmail.readonly` for Gmail. A list you send replaces the whole current list, so include the scopes you want to keep. To build it, start from the current scopes in [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/), then pick from the scopes the connector offers: call [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors) with `identifier` set to the connector, such as `GMAIL`, and read `auth_patterns[].oauth_config.available_scopes[].scope`. You can also add a scope that isn't listed there, using the exact scope string from the provider's own documentation, such as Google's [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes). |
| `oauth_config.token_access_type` | string | No | The `token_access_type` value sent to the provider, for providers that use it, such as Dropbox with `offline`. |
| `oauth_config.token_endpoint_auth_method` | string (enum) | No | How Scalekit sends client credentials to the provider's token URL. `DEFAULT` lets Scalekit choose. One of: `NONE`, `BASIC_AUTH`, `REQUEST_BODY`, `DEFAULT`. |
| `oauth_config.token_uri` | string | No | The provider's token URL. |
| `oauth_config.use_scalekit_creds` | boolean | No | Set to `true` to use Scalekit's own OAuth app instead of yours, for connectors that offer one; otherwise the request fails with `400`. Sending your own `client_id` or `client_secret` sets it to `false` unless you also send it. |
| `oauth_config.user_info_uri` | string | No | The provider's user info URL. |
| `provider_configurations` | object | No | Connector-specific settings to change, for the connectors listed on each field. `provider_domain` can only be set when you create the connection. |
| `provider_configurations.googleads_developer_token` | string | No | Google Ads only: your Google Ads API developer token. See Google's [Obtain a developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token). Responses show it masked. |
| `provider_configurations.microsoft_tenant_id` | string | No | Microsoft connectors only: the ID of your Microsoft Entra tenant, from the **Overview** page of Microsoft Entra ID in the Azure portal. |
| `provider_configurations.provider_domain` | string | No | The regional domain that hosts your account, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region, for connectors that need one. Set it when you create the connection; it can't be changed later and isn't returned. |
| `provider_configurations.slack_connection_type` | string (enum) | No | Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects. One of: `BOT`, `USER`. |
| `provider_configurations.smart_fhir_aud` | string | No | SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in. |
| `provider_configurations.smart_fhir_domain` | string | No | SMART on FHIR only: the domain of the FHIR server. |
| `provider_configurations.trello_app_name` | string | No | Trello only: the name of your Trello app, which Trello shows users when they authorize it. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connection` | object | The connection with its new settings. |
| `connection.auth_mode` | string (enum) | `USER`: each user authorizes their own account. `ORG_WIDE`: one admin-authorized account is shared. One of: `USER`, `ORG_WIDE`. |
| `connection.connection_mcp_url` | string | The URL of an MCP server that Scalekit hosts for this connection alone. Empty when the connection has none. |
| `connection.connection_name` | string | The connection's name, such as `gmail-work`. Your code passes this name as `connection_name` when it creates connected accounts and runs tools. |
| `connection.create_time` | string | When the connection was created. |
| `connection.google_dwd_config` | object | Google domain-wide delegation settings. Present only for `GOOGLE_DWD` connections. |
| `connection.google_dwd_config.required_scopes` | array of string | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `scopes`. |
| `connection.google_dwd_config.scope_selection_allowed` | boolean | Set to `true` to let users choose which of the `scopes` to grant when they connect. |
| `connection.google_dwd_config.scopes` | array of string | The Google scopes to request, such as `https://www.googleapis.com/auth/gmail.readonly`. A list you send replaces the current one. Authorize the same scopes for the service account's client ID in the Google Workspace Admin console, under **Security** > **Access and data control** > **API controls** > **Manage domain wide delegation**. |
| `connection.google_dwd_config.service_account_json` | string | The contents of the service account's JSON key file, as a string. Create the key in the Google Cloud console under **IAM & Admin** > **Service accounts** > your service account > **Keys** > **Add key**. Responses show it masked. |
| `connection.google_dwd_config.token_uri` | string | Google's token URL. Leave it out to use `https://oauth2.googleapis.com/token`. |
| `connection.id` | string | The connection's ID. |
| `connection.oauth_config` | object | OAuth settings. Present for connections that use OAuth. |
| `connection.oauth_config.access_type` | string | The `access_type` value sent to the provider, such as `offline`. |
| `connection.oauth_config.authorize_uri` | string | The provider's authorization URL. |
| `connection.oauth_config.client_id` | string | The client ID of the OAuth app you registered with the provider, such as `123456789012-abc123def456.apps.googleusercontent.com` for a Google app. Get it from the provider's developer console when you create the app (for Gmail: Google Cloud console, **APIs & Services** > **Credentials**, an OAuth client ID of type web application), and add this connection's `redirect_uri` to the app as an authorized redirect URI. Each connector's page under [Connectors](https://docs.scalekit.com/agentkit/connectors/) has the steps for that provider. |
| `connection.oauth_config.client_secret` | string | The client secret of the same OAuth app, from the provider's developer console. Write-only: responses show it masked, such as `********abcd`. Leave it out to keep the stored secret. |
| `connection.oauth_config.extra_authorize_params` | object | Extra query parameters to add to the provider's authorization URL, as name-value pairs, such as `{"hd": "example.com"}`, which asks Google to suggest accounts from that domain. Check the provider's OAuth documentation for the parameters it accepts. Send `{}` to clear them. |
| `connection.oauth_config.optional_scopes` | object | A second set of scopes, for providers that take them in a separate authorization parameter, such as Slack's `user_scope`. Set `field_name` to that parameter's name and `scopes` to its values. |
| `connection.oauth_config.pkce_enabled` | boolean | Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE. |
| `connection.oauth_config.prompt` | string | The `prompt` value sent to the provider, which controls whether the user signs in or consents again, such as `consent`. Send an empty string to send no `prompt`. |
| `connection.oauth_config.redirect_uri` | string | The redirect URI to add to the app you registered with the provider, as an authorized redirect URI. Scalekit sets it; you can't change it. |
| `connection.oauth_config.required_optional_scopes` | array of string | Scopes from `optional_scopes.scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `optional_scopes.scopes`. |
| `connection.oauth_config.required_scopes` | array of string | Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`, such as the read scope your tools always need. Each must also be in `scopes`, or the request fails with `400`. |
| `connection.oauth_config.scope_selection_allowed` | boolean | Set to `true` to let users choose which of the `scopes` to grant when they connect. Scopes in `required_scopes` stay selected. |
| `connection.oauth_config.scopes` | array of string | The OAuth scopes users grant when they connect, such as `https://www.googleapis.com/auth/gmail.readonly` for Gmail. A list you send replaces the whole current list, so include the scopes you want to keep. To build it, start from the current scopes in [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/), then pick from the scopes the connector offers: call [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors) with `identifier` set to the connector, such as `GMAIL`, and read `auth_patterns[].oauth_config.available_scopes[].scope`. You can also add a scope that isn't listed there, using the exact scope string from the provider's own documentation, such as Google's [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes). |
| `connection.oauth_config.token_access_type` | string | The `token_access_type` value sent to the provider, for providers that use it, such as Dropbox with `offline`. |
| `connection.oauth_config.token_endpoint_auth_method` | string (enum) | How Scalekit sends client credentials to the provider's token URL. `DEFAULT` lets Scalekit choose. One of: `NONE`, `BASIC_AUTH`, `REQUEST_BODY`, `DEFAULT`. |
| `connection.oauth_config.token_uri` | string | The provider's token URL. |
| `connection.oauth_config.use_scalekit_creds` | boolean | Set to `true` to use Scalekit's own OAuth app instead of yours, for connectors that offer one; otherwise the request fails with `400`. Sending your own `client_id` or `client_secret` sets it to `false` unless you also send it. |
| `connection.oauth_config.user_info_uri` | string | The provider's user info URL. |
| `connection.provider` | string | The connector this connection uses, such as `GMAIL`. |
| `connection.provider_configurations` | object | Settings for connectors that need extra ones, such as Slack. |
| `connection.provider_configurations.googleads_developer_token` | string | Google Ads only: your Google Ads API developer token. See Google's [Obtain a developer token](https://developers.google.com/google-ads/api/docs/get-started/dev-token). Responses show it masked. |
| `connection.provider_configurations.microsoft_tenant_id` | string | Microsoft connectors only: the ID of your Microsoft Entra tenant, from the **Overview** page of Microsoft Entra ID in the Azure portal. |
| `connection.provider_configurations.provider_domain` | string | The regional domain that hosts your account, such as `mcp-eu.mixpanel.com` for Mixpanel's EU region, for connectors that need one. Set it when you create the connection; it can't be changed later and isn't returned. |
| `connection.provider_configurations.slack_connection_type` | string (enum) | Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects. One of: `BOT`, `USER`. |
| `connection.provider_configurations.smart_fhir_aud` | string | SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in. |
| `connection.provider_configurations.smart_fhir_domain` | string | SMART on FHIR only: the domain of the FHIR server. |
| `connection.provider_configurations.trello_app_name` | string | Trello only: the name of your Trello app, which Trello shows users when they authorize it. |
| `connection.type` | string (enum) | How users authenticate to the app, such as `OAUTH`. It comes from the connector and decides which settings object applies (`oauth_config` or `google_dwd_config`). One of: `OIDC`, `SAML`, `PASSWORD`, `OAUTH`, `PASSWORDLESS`, `BASIC`, `BEARER`, `API_KEY`, `WEBAUTHN`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connection.update_time` | string | When the connection was last changed. |

**Errors**

- `400`: Invalid request - for example, an unknown field, a name that is already used, settings that don't match the connection's type, `required_scopes` that aren't all in `scopes`, or `use_scalekit_creds` on a connector that doesn't offer Scalekit credentials.
- `401`: Authentication required - missing or invalid access token
- `404`: Not found - no connection with this ID. Error code `RESOURCE_NOT_FOUND`.

**Request**

```bash
curl -sS -X PATCH \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/agentkit/connection/conn_70219645518265104" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_name": "gmail-prod",
    "oauth_config": {
      "client_id": "[CLIENT ID]",
      "client_secret": "[CLIENT SECRET]",
      "scopes": [
        "https://www.googleapis.com/auth/gmail.readonly"
      ]
    }
  }'
```

**Response**

```json
{
  "connection": {
    "id": "conn_70219645518265104",
    "type": "OAUTH",
    "create_time": "2026-10-02T14:30:00Z",
    "update_time": "2026-10-02T15:10:00Z",
    "provider": "GMAIL",
    "connection_name": "gmail-prod",
    "auth_mode": "USER",
    "oauth_config": {
      "authorize_uri": "https://accounts.google.com/o/oauth2/v2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "user_info_uri": "https://www.googleapis.com/oauth2/v2/userinfo",
      "client_id": "[CLIENT ID]",
      "client_secret": "********abcd",
      "scopes": [
        "https://www.googleapis.com/auth/gmail.readonly"
      ],
      "redirect_uri": "https://your-env.scalekit.dev/sso/v1/oauth/conn_70219645518265104/callback",
      "pkce_enabled": false,
      "use_scalekit_creds": false,
      "extra_authorize_params": {},
      "token_endpoint_auth_method": "DEFAULT",
      "scope_selection_allowed": false,
      "required_scopes": [],
      "required_optional_scopes": []
    }
  }
}
```

**Python SDK:** `scalekit_client.actions.update_connection`

Changes a connection's name or settings. Pass the connection by name, or by ID with `connection_id`. Only the fields you pass change.

```python
scalekit_client.actions.update_connection(
    connection_name: Optional[str] = None,
    connection_id: Optional[str] = None,
    new_connection_name: Optional[str] = None,
    oauth: Optional[OAuthSettings] = None,
    google_dwd: Optional[GoogleDWDSettings] = None,
    provider_configurations: Optional[ProviderConfigurations] = None,
) -> AgentKitConnection
```

Example:

```python
from scalekit.actions.connections import OAuthSettings

result = scalekit_client.actions.update_connection(
    connection_id="conn_70219645518265104",
    new_connection_name="gmail-prod",
    oauth=OAuthSettings(
        client_id="[CLIENT ID]",
        client_secret="[CLIENT SECRET]",
        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
    ),
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection's current name, such as `gmail-work`. Use this or `connection_id`. |
| `connection_id` | `Optional[str]` | No | The connection's ID, such as `conn_70219645518265104`. Use this or `connection_name`. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |
| `new_connection_name` | `Optional[str]` | No | A new name for the connection, such as `gmail-prod`. Update the `connection_name` your code passes when you rename one. |
| `oauth` | `Optional[OAuthSettings]` | No | The OAuth settings to change, as `OAuthSettings`. Each field you leave as `None` keeps its value; pass `[]` or `{}` to clear a list or map. `client_id` and `client_secret` come from the OAuth app you registered with the provider, such as a Google Cloud OAuth client ID for Gmail; add the connection's `redirect_uri` to that app. `scopes` replaces the whole list, such as `["https://www.googleapis.com/auth/gmail.readonly"]`. Start from the current scopes in [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/), and pick more from `auth_patterns[].oauth_config.available_scopes` in [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors). You can also add a scope that isn't listed there, using the exact string from the provider's documentation, such as Google's [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes). Other fields: `required_scopes`, `scope_selection_allowed`, `use_scalekit_creds`, `access_type`, `prompt`, `pkce_enabled`, `extra_authorize_params` and `token_endpoint_auth_method`, described in the request body above. |
| `google_dwd` | `Optional[GoogleDWDSettings]` | No | Google domain-wide delegation settings to change, as `GoogleDWDSettings(service_account_json=, scopes=)`. Only for `GOOGLE_DWD` connections. |
| `provider_configurations` | `Optional[ProviderConfigurations]` | No | Connector-specific settings to change, as `ProviderConfigurations`, such as `ProviderConfigurations(slack_connection_type="BOT")` for Slack. |

Returns `AgentKitConnection`.

**Node.js SDK:** `scalekit.actions.updateConnection`

Changes a connection's name or settings. Pass the connection by `connectionName` or `connectionId`. Only the fields you pass change.

```ts
scalekit.actions.updateConnection(
  params: {
    connectionName?: string;
    connectionId?: string;
    newConnectionName?: string;
    oauth?: AgentKitOAuthSettings;
    googleDwd?: AgentKitGoogleDwdSettings;
    providerConfigurations?: AgentKitProviderConfigurations;
  },
): Promise<AgentKitConnection>
```

Example:

```ts
const result = await scalekit.actions.updateConnection({
  connectionId: "conn_70219645518265104",
  newConnectionName: "gmail-prod",
  oauth: {
    clientId: "[CLIENT ID]",
    clientSecret: "[CLIENT SECRET]",
    scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
  },
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | No | The connection's current name, such as `gmail-work`. Use this or `connectionId`. |
| `connectionId` | `string` | No | The connection's ID, such as `conn_70219645518265104`. Use this or `connectionName`. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |
| `newConnectionName` | `string` | No | A new name for the connection, such as `gmail-prod`. Update the `connectionName` your code passes when you rename one. |
| `oauth` | `AgentKitOAuthSettings` | No | The OAuth settings to change, as `{ clientId?, clientSecret?, scopes?, ... }`. Each field you leave out keeps its value; pass `[]` or `{}` to clear a list or map. `clientId` and `clientSecret` come from the OAuth app you registered with the provider, such as a Google Cloud OAuth client ID for Gmail; add the connection's `redirect_uri` to that app. `scopes` replaces the whole list, such as `["https://www.googleapis.com/auth/gmail.readonly"]`. Start from the current scopes in [Get a connection](https://docs.scalekit.com/agentkit/reference/connections/get-a-connection/), and pick more from `auth_patterns[].oauth_config.available_scopes` in [List connectors](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/#list-connectors). You can also add a scope that isn't listed there, using the exact string from the provider's documentation, such as Google's [Gmail API scopes](https://developers.google.com/workspace/gmail/api/auth/scopes). Other fields: `requiredScopes`, `scopeSelectionAllowed`, `useScalekitCreds`, `accessType`, `prompt`, `pkceEnabled`, `extraAuthorizeParams` and `tokenEndpointAuthMethod`, described in the request body above in snake_case. Send at most one of `oauth` or `googleDwd`. |
| `googleDwd` | `AgentKitGoogleDwdSettings` | No | Google domain-wide delegation settings to change, as `{ serviceAccountJson?, scopes?, ... }`. Only for `GOOGLE_DWD` connections. |
| `providerConfigurations` | `AgentKitProviderConfigurations` | No | Connector-specific settings to change, such as `{ slackConnectionType: 'BOT' }` for Slack. Send it with `oauth`, or on its own. |

Returns `Promise<AgentKitConnection>`.

**Used in**

- [Set up a connection](https://docs.scalekit.com/agentkit/connections/)

## Delete a connection

`DELETE /api/v1/connections/{connection_id}`

Deletes a connection. It fails while connected accounts or Virtual MCP servers still use the connection. Delete its connected accounts first with [Delete a connected account](https://docs.scalekit.com/agentkit/reference/connected-accounts/delete-a-connected-account/), and remove it from each server with [Update a Virtual MCP server](https://docs.scalekit.com/agentkit/reference/virtual-mcp-servers/update-a-virtual-mcp-server/).

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_id` | string | Yes | The connection's ID, such as `conn_70219645518265104`. Find it in the `id` field of the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

**Errors**

- `400`: Invalid request - connected accounts or Virtual MCP servers still use the connection.
- `401`: Authentication required - missing or invalid access token
- `404`: Not found - no connection with this ID. Error code `RESOURCE_NOT_FOUND`.

**Request**

```bash
curl -sS -X DELETE \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connections/conn_70219645518265104" \
  -H "Authorization: Bearer $TOKEN"
```

**Response**

```json
{}
```

**Python SDK:** `scalekit_client.actions.delete_connection`

Deletes a connection. Pass the connection's name, or its ID with `connection_id`. It fails while connected accounts or Virtual MCP servers still use the connection, so delete those accounts and remove the connection from those servers first.

```python
scalekit_client.actions.delete_connection(
    connection_name: Optional[str] = None,
    connection_id: Optional[str] = None,
) -> None
```

Example:

```python
result = scalekit_client.actions.delete_connection(
    connection_id="conn_70219645518265104",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection's name, such as `gmail-work`. |
| `connection_id` | `Optional[str]` | No | The connection's ID, such as `conn_70219645518265104`, instead of its name. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

Returns `None`: Nothing. The call raises an error if it fails.

**Node.js SDK:** `scalekit.actions.deleteConnection`

Deletes a connection. Pass the connection's name or ID. It fails while connected accounts or Virtual MCP servers still use the connection, so delete those accounts and remove the connection from those servers first.

```ts
scalekit.actions.deleteConnection(
  connection: string | ConnectionRef,
): Promise<void>
```

Example:

```ts
const result = await scalekit.actions.deleteConnection({ connectionId: "conn_70219645518265104" });
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection` | `string \| ConnectionRef` | Yes | The connection's name, such as `gmail-work`, or its ID, such as `conn_70219645518265104`, as a string, or `{ connectionName }` or `{ connectionId }`. |

Returns `Promise<void>`: Nothing. The promise rejects if the call fails.


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |