Get a connection

GET/api/v1/agentkit/connection/{connection_identifier}

Returns a connection with its settings, looked up by its name or its ID. Use it to check the scopes the connection requests, or to copy its redirect_uri into the app you registered with the provider. Secrets come back masked.

This page as markdown Connections overview

Authorization

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

Path parameters

connection_identifierstringrequired

The connection's name, such as gmail-work, or its ID, such as conn_70219645518265104. Both are in the List connections response.

scalekit_client.actions.get_connection

Gets a connection by name or ID. Pass the connection's name, or its ID with connection_id.

scalekit_client.actions.get_connection(
    connection_name: Optional[str] = None,
    connection_id: Optional[str] = None,
) -> AgentKitConnection

Parameters

connection_nameOptional[str]

The connection's name, such as gmail-work.

connection_idOptional[str]

The connection's ID, such as conn_70219645518265104, instead of its name. Both are in the List connections response.

Returns AgentKitConnection.

From scalekit-sdk-python 2.22.0.

scalekit.actions.getConnection

Gets a connection by name or ID. Pass the connection's name or ID.

scalekit.actions.getConnection(
  connection: string | ConnectionRef,
): Promise<AgentKitConnection>

Parameters

connectionstring | ConnectionRefrequired

The connection's name, such as gmail-work, or its ID, such as conn_70219645518265104, as a string, or { connectionName } or { connectionId }. Both are in the List connections response.

Returns Promise<AgentKitConnection>.

From @scalekit-sdk/node 2.21.0.

Response 200

connectionobject

The connection.

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

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.

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.

401Authentication required - missing or invalid access token

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

Used in

Set up a connection

Request

curl -sS -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/agentkit/connection/gmail-work" \
  -H "Authorization: Bearer $TOKEN"

result = scalekit_client.actions.get_connection(
    connection_name="gmail-work",
)

const result = await scalekit.actions.getConnection("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
    "connection_mcp_url": "https://your-env.scalekit.dev/mcp/v3/connections/gmail-work"
34
  }
35
}