> **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/)

---

# 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/)


Part of [Connections](https://docs.scalekit.com/agentkit/reference/connections/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md


---

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