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.

This page as markdown Connections overview

Authorization

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

Body

providerstringrequired

The connector's identifier, such as GMAIL. To find a connector's identifier, call List connectors and read identifier.

auth_modestring (enum)

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.

USERORG_WIDE

connection_namestring

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_configurationsobject

Extra settings, only for the connectors named on each field, such as provider_domain for a connector with regional domains.

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

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

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

Parameters

providerstrrequired

The connector's identifier, such as GMAIL. To find it, call List connectors and read identifier.

connection_nameOptional[str]

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_modeOptional[AuthMode]

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_domainOptional[str]

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.

From scalekit-sdk-python 2.22.0.

scalekit.actions.createConnection

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

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

Parameters

providerstringrequired

The connector's identifier, such as GMAIL. To find it, call List connectors and read identifier.

connectionNamestring

authModeAgentKitAuthMode

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

providerDomainstring

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.

From @scalekit-sdk/node 2.21.0.

Response 200

connectionobject

The connection that was created.

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

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.

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

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.

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.

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

401Authentication required - missing or invalid access token

Used in

Set up a connection

Request

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

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

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

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-02T14:30:00Z",
7
    "provider": "GMAIL",
8
    "connection_name": "gmail-work",
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": "",
15
      "client_secret": "",
16
      "scopes": [
17
        "https://www.googleapis.com/auth/gmail.readonly",
18
        "https://www.googleapis.com/auth/gmail.modify",
19
        "https://www.googleapis.com/auth/gmail.send",
20
        "https://www.googleapis.com/auth/contacts.readonly",
21
        "https://www.googleapis.com/auth/contacts.other.readonly",
22
        "https://www.googleapis.com/auth/gmail.settings.basic"
23
      ],
24
      "redirect_uri": "https://your-env.scalekit.dev/sso/v1/oauth/conn_70219645518265104/callback",
25
      "pkce_enabled": false,
26
      "use_scalekit_creds": false,
27
      "extra_authorize_params": {},
28
      "token_endpoint_auth_method": "DEFAULT",
29
      "scope_selection_allowed": false,
30
      "required_scopes": [],
31
      "required_optional_scopes": []
32
    }
33
  }
34
}