SCscalekit
App Connections

Create a connection

Changed on

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.

post/api/v1/agentkit/connection

Request

Request body

auth_mode'USER' | 'ORG_WIDE'

How users authorize the connection: USER or ORG_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.

providerstring

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

Example request

{
  "connection_name": "gmail-work",
  "provider": "GMAIL",
  "provider_configurations": {
    "googleads_developer_token": "ABcDeFgHiJkLmNoPqRsTuV",
    "microsoft_tenant_id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
    "provider_domain": "mcp-eu.mixpanel.com",
    "slack_connection_type": "USER",
    "smart_fhir_aud": "https://fhir.example.com/r4",
    "smart_fhir_domain": "fhir.example.com",
    "trello_app_name": "My Trello App"
  }
}

Response

The connection that was created.

Example response

{
  "connection": {
    "connection_mcp_url": "https://yourapp.scalekit.dev/mcp/v3/connections/gmail-work",
    "connection_name": "gmail-work",
    "create_time": "2023-01-15T14:30:00Z",
    "google_dwd_config": {
      "required_scopes": [
        "https://www.googleapis.com/auth/gmail.readonly"
      ],
      "scope_selection_allowed": true,
      "scopes": [
        "https://www.googleapis.com/auth/gmail.readonly"
      ],
      "service_account_json": "{\"type\":\"service_account\",\"project_id\":\"my-project\",\"private_key_id\":\"0123456789abcdef\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\nMIIEvQ...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"dwd-sa@my-project.iam.gserviceaccount.com\",\"client_id\":\"123456789012345678901\"}"
    },
    "id": "conn_2123312131125533",
    "oauth_config": {
      "access_type": "offline",
      "authorize_uri": "https://youridp.com/service/oauth/authorize",
      "client_id": "123456789012-abc123def456.apps.googleusercontent.com",
      "client_secret": "GOCSPX-your-client-secret",
      "extra_authorize_params": {
        "hd": "example.com"
      },
      "optional_scopes": {
        "field_name": "optional_scope or bot_scope",
        "scopes": [
          "scope1",
          "scope2"
        ]
      },
      "pkce_enabled": true,
      "prompt": "consent",
      "redirect_uri": "https://yourapp.scalekit.dev/sso/v1/oauth/conn_24832952112323587/callback",
      "required_optional_scopes": [
        "search:read"
      ],
      "required_scopes": [
        "https://www.googleapis.com/auth/gmail.readonly"
      ],
      "scope_selection_allowed": true,
      "scopes": [
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/gmail.send"
      ],
      "token_access_type": "offline",
      "token_uri": "https://youridp.com/service/oauth/token",
      "use_scalekit_creds": true,
      "user_info_uri": "https://youridp.com/service/oauth/userinfo"
    },
    "provider": "GMAIL",
    "provider_configurations": {
      "googleads_developer_token": "ABcDeFgHiJkLmNoPqRsTuV",
      "microsoft_tenant_id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
      "provider_domain": "mcp-eu.mixpanel.com",
      "slack_connection_type": "USER",
      "smart_fhir_aud": "https://fhir.example.com/r4",
      "smart_fhir_domain": "fhir.example.com",
      "trello_app_name": "My Trello App"
    },
    "update_time": "2023-02-20T09:15:30Z"
  }
}

Changes