--- title: "Update a connection" method: PATCH path: "/api/v1/agentkit/connection/{connection_id}" tags: ["App Connections"] --- # Update a connection `PATCH /api/v1/agentkit/connection/{connection_id}` ## Request - Base URL: `https://$SCALEKIT_ENVIRONMENT_URL` - URL: `https://$SCALEKIT_ENVIRONMENT_URL/api/v1/agentkit/connection/{connection_id}` - Auth: OAuth 2 - Client credentials - Token URL: `https://$SCALEKIT_ENVIRONMENT_URL/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](/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 - `connection_id` string, required ## Request body - ConnectionsAppConnectionUpdate: The settings to change. Send only what you want to change. - `connection_name` string: 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` ConnectionsGoogleDWDConfig - `required_scopes` string[]: Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `scopes`. - `scope_selection_allowed` boolean: Set to `true` to let users choose which of the `scopes` to grant when they connect. - `scopes` 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**. - `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. - `token_uri` string: Google's token URL. Leave it out to use `https://oauth2.googleapis.com/token`. - `oauth_config` ConnectionsAppOAuthConfig: OAuth settings for the connection. - `access_type` string: The `access_type` value sent to the provider, such as `offline`. - `authorize_uri` string: The provider's authorization URL. - `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](/agentkit/connectors/) has the steps for that provider. - `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. - `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. - `optional_scopes` ConnectionsOptionalScopes - `field_name` string: 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. - `scopes` string[]: List of optional scopes that can be requested during authentication - `pkce_enabled` boolean: Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE. - `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`. - `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. - `required_optional_scopes` 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`. - `required_scopes` 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`. - `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. - `scopes` 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](/agentkit/reference/connections/get-a-connection/), then pick from the scopes the connector offers: call [List connectors](/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). - `token_access_type` string: The `token_access_type` value sent to the provider, for providers that use it, such as Dropbox with `offline`. - `token_endpoint_auth_method` 'NONE' | 'BASIC_AUTH' | 'REQUEST_BODY' | 'DEFAULT': How Scalekit sends client credentials to the provider's token URL. - `token_uri` string: The provider's token URL. - `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. - `user_info_uri` string: The provider's user info URL. - `provider_configurations` ConnectionsAppProviderConfigurations: Settings for connectors that need extra ones. - `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. - `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. - `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. - `slack_connection_type` 'BOT' | 'USER': Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects. - `smart_fhir_aud` string: SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in. - `smart_fhir_domain` string: SMART on FHIR only: the domain of the FHIR server. - `trello_app_name` string: Trello only: the name of your Trello app, which Trello shows users when they authorize it. ## Response `200` The connection with its new settings. - ConnectionsUpdateAppConnectionResponse: The connection with its new settings. - `connection` ConnectionsAppConnection: A connection: your environment's settings for one connector. - `auth_mode` 'USER' | 'ORG_WIDE': How users authorize the connection: `USER` or `ORG_WIDE`. - `connection_mcp_url` string: The URL of an MCP server that Scalekit hosts for this connection alone. Empty when the connection has none. - `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. - `create_time` string, date-time: When the connection was created. - `google_dwd_config` ConnectionsGoogleDWDConfig - `required_scopes` string[]: Scopes from `scopes` that users can't deselect when `scope_selection_allowed` is `true`. Each must also be in `scopes`. - `scope_selection_allowed` boolean: Set to `true` to let users choose which of the `scopes` to grant when they connect. - `scopes` 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**. - `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. - `token_uri` string: Google's token URL. Leave it out to use `https://oauth2.googleapis.com/token`. - `id` string: The connection's ID. - `oauth_config` ConnectionsAppOAuthConfig: OAuth settings for the connection. - `access_type` string: The `access_type` value sent to the provider, such as `offline`. - `authorize_uri` string: The provider's authorization URL. - `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](/agentkit/connectors/) has the steps for that provider. - `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. - `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. - `optional_scopes` ConnectionsOptionalScopes - `field_name` string: 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. - `scopes` string[]: List of optional scopes that can be requested during authentication - `pkce_enabled` boolean: Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE. - `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`. - `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. - `required_optional_scopes` 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`. - `required_scopes` 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`. - `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. - `scopes` 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](/agentkit/reference/connections/get-a-connection/), then pick from the scopes the connector offers: call [List connectors](/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). - `token_access_type` string: The `token_access_type` value sent to the provider, for providers that use it, such as Dropbox with `offline`. - `token_endpoint_auth_method` 'NONE' | 'BASIC_AUTH' | 'REQUEST_BODY' | 'DEFAULT': How Scalekit sends client credentials to the provider's token URL. - `token_uri` string: The provider's token URL. - `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. - `user_info_uri` string: The provider's user info URL. - `provider` string: The connector this connection uses, such as `GMAIL`. - `provider_configurations` ConnectionsAppProviderConfigurations: Settings for connectors that need extra ones. - `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. - `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. - `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. - `slack_connection_type` 'BOT' | 'USER': Slack only: `BOT` to act as your Slack app's bot user, or `USER` to act as the user who connects. - `smart_fhir_aud` string: SMART on FHIR only: the base URL of the FHIR server, sent as the `aud` parameter when users sign in. - `smart_fhir_domain` string: SMART on FHIR only: the domain of the FHIR server. - `trello_app_name` string: Trello only: the name of your Trello app, which Trello shows users when they authorize it. - `type` 'OIDC' | 'SAML' | 'PASSWORD' | 'OAUTH' | 'PASSWORDLESS' | 'BASIC' | 'BEARER' | 'API_KEY' | 'WEBAUTHN' | 'OAUTH_M2M' | 'TRELLO_OAUTH1' | 'GOOGLE_DWD' | 'TRUSTED_IDP' | 'SMART_FHIR' | 'NO_AUTH' - `update_time` string, date-time: When the connection was last changed. ## Other responses - `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`. ## Changes - **2026-10-30** `f6c5d8349d4a`: 1 info - endpoint added [Operation history](https://skmtc.dev/scalekit/apis/scalekit-api-reference/changes/api/v1/agentkit/connection/:connection_id/patch.md) --- [API](https://skmtc.dev/scalekit/apis/scalekit-api-reference.md) - [All operations](https://skmtc.dev/scalekit/apis/scalekit-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/scalekit/apis/scalekit-api-reference/revisions/f47f1022d844?raw)