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. Sending your own client_id or client_secret switches the connection to your credentials, unless you also set use_scalekit_creds.

This page as markdown Connections overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Path parameters

connection_idstringrequired

The connection's ID, such as conn_70219645518265104. Use the ID, not the name. Find it in the id field of the Create, Get or List connections response.

Body

connection_namestring

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_configobject

Google domain-wide delegation settings to change. Only for connections whose type is GOOGLE_DWD.

Show 5 child attributes

required_scopesarray of string

Scopes from scopes that users can't deselect when scope_selection_allowed is true. Each must also be in scopes.

scope_selection_allowedboolean

Set to true to let users choose which of the scopes to grant when they connect.

scopesarray 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.

service_account_jsonstring

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_uristring

Google's token URL. Leave it out to use https://oauth2.googleapis.com/token.

oauth_configobject

OAuth settings to change, such as client_id, client_secret and scopes. For connections that use OAuth, such as type OAUTH.

Show 18 child attributes

access_typestring

The access_type value sent to the provider, such as offline.

authorize_uristring

The provider's authorization URL.

client_idstring

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 has the steps for that provider.

client_secretstring

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_paramsobject

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_scopesobject

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.

Show 2 child attributes

field_namestring

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.

scopesarray of string

List of optional scopes that can be requested during authentication

pkce_enabledboolean

Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE.

promptstring

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_uristring

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_scopesarray 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.

required_scopesarray 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.

scope_selection_allowedboolean

Set to true to let users choose which of the scopes to grant when they connect. Scopes in required_scopes stay selected.

scopesarray 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, then pick from the scopes the connector offers: call 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.

token_access_typestring

The token_access_type value sent to the provider, for providers that use it, such as Dropbox with offline.

token_endpoint_auth_methodstring (enum)

How Scalekit sends client credentials to the provider's token URL. DEFAULT lets Scalekit choose.

NONEBASIC_AUTHREQUEST_BODYDEFAULT

token_uristring

The provider's token URL.

use_scalekit_credsboolean

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_uristring

The provider's user info URL.

provider_configurationsobject

Connector-specific settings to change, for the connectors listed on each field. provider_domain can only be set when you create the connection.

Show 7 child attributes

googleads_developer_tokenstring

Google Ads only: your Google Ads API developer token. See Google's Obtain a developer token. Responses show it masked.

microsoft_tenant_idstring

Microsoft connectors only: the ID of your Microsoft Entra tenant, from the Overview page of Microsoft Entra ID in the Azure portal.

provider_domainstring

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_typestring (enum)

Slack only: BOT to act as your Slack app's bot user, or USER to act as the user who connects.

BOTUSER

smart_fhir_audstring

SMART on FHIR only: the base URL of the FHIR server, sent as the aud parameter when users sign in.

smart_fhir_domainstring

SMART on FHIR only: the domain of the FHIR server.

trello_app_namestring

Trello only: the name of your Trello app, which Trello shows users when they authorize it.

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.

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

Parameters

connection_nameOptional[str]

The connection's current name, such as gmail-work. Use this or connection_id.

connection_idOptional[str]

The connection's ID, such as conn_70219645518265104. Use this or connection_name. Both are in the List connections response.

new_connection_nameOptional[str]

A new name for the connection, such as gmail-prod. Update the connection_name your code passes when you rename one.

oauthOptional[OAuthSettings]

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, and pick more from auth_patterns[].oauth_config.available_scopes in 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. 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_dwdOptional[GoogleDWDSettings]

Google domain-wide delegation settings to change, as GoogleDWDSettings(service_account_json=, scopes=). Only for GOOGLE_DWD connections.

provider_configurationsOptional[ProviderConfigurations]

Connector-specific settings to change, as ProviderConfigurations, such as ProviderConfigurations(slack_connection_type="BOT") for Slack.

Returns AgentKitConnection.

From scalekit-sdk-python 2.22.0.

scalekit.actions.updateConnection

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

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

Parameters

connectionNamestring

The connection's current name, such as gmail-work. Use this or connectionId.

connectionIdstring

The connection's ID, such as conn_70219645518265104. Use this or connectionName. Both are in the List connections response.

newConnectionNamestring

A new name for the connection, such as gmail-prod. Update the connectionName your code passes when you rename one.

oauthAgentKitOAuthSettings

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, and pick more from auth_patterns[].oauth_config.available_scopes in 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. 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.

googleDwdAgentKitGoogleDwdSettings

Google domain-wide delegation settings to change, as { serviceAccountJson?, scopes?, ... }. Only for GOOGLE_DWD connections.

providerConfigurationsAgentKitProviderConfigurations

Connector-specific settings to change, such as { slackConnectionType: 'BOT' } for Slack. Send it with oauth, or on its own.

Returns Promise<AgentKitConnection>.

From @scalekit-sdk/node 2.21.0.

Response 200

connectionobject

The connection with its new settings.

Show 11 child attributes

auth_modestring (enum)

USER: each user authorizes their own account. ORG_WIDE: one admin-authorized account is shared.

USERORG_WIDE

connection_mcp_urlstring

The URL of an MCP server that Scalekit hosts for this connection alone. Empty when the connection has none.

connection_namestring

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_timestring

When the connection was created.

google_dwd_configobject

Google domain-wide delegation settings. Present only for GOOGLE_DWD connections.

Show 5 child attributes

required_scopesarray of string

Scopes from scopes that users can't deselect when scope_selection_allowed is true. Each must also be in scopes.

scope_selection_allowedboolean

Set to true to let users choose which of the scopes to grant when they connect.

scopesarray of string

service_account_jsonstring

token_uristring

Google's token URL. Leave it out to use https://oauth2.googleapis.com/token.

idstring

The connection's ID.

oauth_configobject

OAuth settings. Present for connections that use OAuth.

Show 18 child attributes

access_typestring

The access_type value sent to the provider, such as offline.

authorize_uristring

The provider's authorization URL.

client_idstring

client_secretstring

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_paramsobject

optional_scopesobject

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.

pkce_enabledboolean

Whether Scalekit adds PKCE to the authorization request. Turn it on when the provider requires or supports PKCE.

promptstring

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_uristring

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_scopesarray 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.

required_scopesarray 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.

scope_selection_allowedboolean

Set to true to let users choose which of the scopes to grant when they connect. Scopes in required_scopes stay selected.

scopesarray of string

token_access_typestring

The token_access_type value sent to the provider, for providers that use it, such as Dropbox with offline.

token_endpoint_auth_methodstring (enum)

How Scalekit sends client credentials to the provider's token URL. DEFAULT lets Scalekit choose.

NONEBASIC_AUTHREQUEST_BODYDEFAULT

token_uristring

The provider's token URL.

use_scalekit_credsboolean

user_info_uristring

The provider's user info URL.

providerstring

The connector this connection uses, such as GMAIL.

provider_configurationsobject

Settings for connectors that need extra ones, such as Slack.

Show 7 child attributes

googleads_developer_tokenstring

Google Ads only: your Google Ads API developer token. See Google's Obtain a developer token. Responses show it masked.

microsoft_tenant_idstring

Microsoft connectors only: the ID of your Microsoft Entra tenant, from the Overview page of Microsoft Entra ID in the Azure portal.

provider_domainstring

slack_connection_typestring (enum)

Slack only: BOT to act as your Slack app's bot user, or USER to act as the user who connects.

BOTUSER

smart_fhir_audstring

SMART on FHIR only: the base URL of the FHIR server, sent as the aud parameter when users sign in.

smart_fhir_domainstring

SMART on FHIR only: the domain of the FHIR server.

trello_app_namestring

Trello only: the name of your Trello app, which Trello shows users when they authorize it.

typestring (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).

OIDCSAMLPASSWORDOAUTHPASSWORDLESSBASICBEARERAPI_KEYWEBAUTHNOAUTH_M2MTRELLO_OAUTH1GOOGLE_DWDTRUSTED_IDPSMART_FHIRNO_AUTH

update_timestring

When the connection was last changed.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid 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.

401Authentication required - missing or invalid access token

404Not found - no connection with this ID. Error code RESOURCE_NOT_FOUND.

Used in

Set up a connection

Request

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"
      ]
    }
  }'

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"],
    ),
)

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"],
  },
});

Response 200

1
{
2
  "connection": {
3
    "id": "conn_70219645518265104",
4
    "type": "OAUTH",
5
    "create_time": "2026-10-02T14:30:00Z",
6
    "update_time": "2026-10-02T15:10:00Z",
7
    "provider": "GMAIL",
8
    "connection_name": "gmail-prod",
9
    "auth_mode": "USER",
10
    "oauth_config": {
11
      "authorize_uri": "https://accounts.google.com/o/oauth2/v2/auth",
12
      "token_uri": "https://oauth2.googleapis.com/token",
13
      "user_info_uri": "https://www.googleapis.com/oauth2/v2/userinfo",
14
      "client_id": "[CLIENT ID]",
15
      "client_secret": "********abcd",
16
      "scopes": [
17
        "https://www.googleapis.com/auth/gmail.readonly"
18
      ],
19
      "redirect_uri": "https://your-env.scalekit.dev/sso/v1/oauth/conn_70219645518265104/callback",
20
      "pkce_enabled": false,
21
      "use_scalekit_creds": false,
22
      "extra_authorize_params": {},
23
      "token_endpoint_auth_method": "DEFAULT",
24
      "scope_selection_allowed": false,
25
      "required_scopes": [],
26
      "required_optional_scopes": []
27
    }
28
  }
29
}