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

---

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

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_identifier` | string | Yes | The connection's name, such as `gmail-work`, or its ID, such as `conn_70219645518265104`. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connection` | object | The connection. |
| `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**

- `401`: Authentication required - missing or invalid access token
- `404`: Not found - no connection with this name or ID. Error code `RESOURCE_NOT_FOUND`.

**Request**

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

**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": []
    },
    "connection_mcp_url": "https://your-env.scalekit.dev/mcp/v3/connections/gmail-work"
  }
}
```

**Python SDK:** `scalekit_client.actions.get_connection`

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

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

Example:

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection's name, such as `gmail-work`. |
| `connection_id` | `Optional[str]` | No | The connection's ID, such as `conn_70219645518265104`, instead of its name. Both are in the [List connections](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

Returns `AgentKitConnection`.

**Node.js SDK:** `scalekit.actions.getConnection`

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

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

Example:

```ts
const result = await scalekit.actions.getConnection("gmail-work");
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection` | `string \| ConnectionRef` | Yes | 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](https://docs.scalekit.com/agentkit/reference/connections/list-connections/) response. |

Returns `Promise<AgentKitConnection>`.

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