> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connected accounts

A connected account is one user's link to one connection, and holds that user's credentials for the app. See [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts/) for when to check, refresh or delete one.

**SDK helpers.** `get_or_create_connected_account` (Python) and `getOrCreateConnectedAccount` (Node.js) get the user's connected account for a connection, or create it without credentials when there isn't one; [Authorize a user](https://docs.scalekit.com/agentkit/tools/authorize/) and [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts/) use them. `actions.providers.list_providers` (Python) and `actions.providers.listProviders` (Node.js) list connectors with their `identifier`, as [Create a connector](https://docs.scalekit.com/agentkit/bring-your-own-connector/create-connector/) shows.

One page per endpoint, each with its own markdown copy:

| Endpoint | Request | What it does | Python SDK | Node.js SDK |
| --- | --- | --- | --- | --- |
| [Create a connected account](https://docs.scalekit.com/agentkit/reference/connected-accounts/create-a-connected-account.md) | `POST /api/v1/connected_accounts` | Store a user's OAuth tokens or API key for one connection. | `actions.create_connected_account` | `actions.createConnectedAccount` |
| [Get a connected account](https://docs.scalekit.com/agentkit/reference/connected-accounts/get-a-connected-account.md) | `GET /api/v1/connected_accounts/details` | Get an account's status, connection and settings, without its credentials. | `actions.get_connected_account_details` | REST only |
| [List connected accounts](https://docs.scalekit.com/agentkit/reference/connected-accounts/list-connected-accounts.md) | `GET /api/v1/connected_accounts` | List accounts, filtered by connection, user, provider or organization. | `actions.list_connected_accounts` | `actions.listConnectedAccounts` |
| [Search connected accounts](https://docs.scalekit.com/agentkit/reference/connected-accounts/search-connected-accounts.md) | `GET /api/v1/connected_accounts:search` | Find accounts whose identifier, provider or connection matches a text query. | REST only | REST only |
| [Update a connected account](https://docs.scalekit.com/agentkit/reference/connected-accounts/update-a-connected-account.md) | `PUT /api/v1/connected_accounts` | Store new tokens or an API key for an account, or change its settings. | `actions.update_connected_account` | `actions.updateConnectedAccount` |
| [Get a connected account's credentials](https://docs.scalekit.com/agentkit/reference/connected-accounts/get-connected-account-credentials.md) | `GET /api/v1/connected_accounts/auth` | Get an account with its OAuth tokens or API key, to call the app yourself. | `actions.get_connected_account` | `actions.getConnectedAccount` |
| [Delete a connected account](https://docs.scalekit.com/agentkit/reference/connected-accounts/delete-a-connected-account.md) | `POST /api/v1/connected_accounts:delete` | Delete an account and the user's stored credentials. | `actions.delete_connected_account` | `actions.deleteConnectedAccount` |


## Create a connected account

`POST /api/v1/connected_accounts`

Creates a connected account for one user and one connection, with credentials your app already holds: OAuth tokens, or an API key or other static credentials. To have the user connect their own account instead, send them an authorization link. Returns the account with its ID and status.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connected_account` | object | Yes | Details of the connected account to create. |
| `connected_account.api_config` | object | No | Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. |
| `connected_account.authorization_details` | object | No | Authentication credentials for the connected account. Include OAuth tokens (access_token, refresh_token, scopes) or static auth details (API keys, bearer tokens). Can be provided later via update. |
| `connected_account.authorization_details.google_dwd` | object | No | Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. Send only subject in requests; access_token, scopes, and token_expires_at are response-only. |
| `connected_account.authorization_details.oauth_token` | object | No | OAuth 2.0 credentials. |
| `connected_account.authorization_details.static_auth` | object | No | Static credentials, such as an API key. |
| `connected_account.authorization_details.trusted_idp` | object | No | Credentials for a connection that signs in through a trusted identity provider, such as AWS Redshift. Send only `db_user`. Responses include `access_key_id` and `expiry`, never the secret key or session token. |
| `connector` | string | Yes | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | string | No | Your app's ID for the user. Use a stable internal ID, not an email address. Required unless you key the account by `organization_id`. |
| `organization_id` | string | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `user_id` | string | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connected_account` | object | The newly created connected account with its unique identifier, status, and complete authorization details including access tokens. |
| `connected_account.api_config` | object | Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. |
| `connected_account.authorization_details` | object | The account's credentials. Set the one that matches the connection's auth type - `oauth_token`, `static_auth`, `google_dwd` or `trusted_idp`. |
| `connected_account.authorization_details.google_dwd` | object | Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. Send only subject in requests; access_token, scopes, and token_expires_at are response-only. |
| `connected_account.authorization_details.oauth_token` | object | OAuth 2.0 credentials. |
| `connected_account.authorization_details.static_auth` | object | Static credentials, such as an API key. |
| `connected_account.authorization_details.trusted_idp` | object | Credentials for a connection that signs in through a trusted identity provider, such as AWS Redshift. Send only `db_user`. Responses include `access_key_id` and `expiry`, never the secret key or session token. |
| `connected_account.authorization_type` | string (enum) | Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. One of: `OAUTH`, `API_KEY`, `BASIC_AUTH`, `BEARER_TOKEN`, `CUSTOM`, `BASIC`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connected_account.connection_id` | string | Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. |
| `connected_account.connector` | string | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_account.id` | string | Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'. |
| `connected_account.identifier` | string | Your app's ID for the user, the value passed when the account was created. |
| `connected_account.is_org_wide_credential` | boolean | Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account. |
| `connected_account.last_used_at` | string | Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. |
| `connected_account.provider` | string | The app the account connects to, such as `GMAIL` or `SLACK`. |
| `connected_account.status` | string (enum) | Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. One of: `ACTIVE`, `EXPIRED`, `PENDING_AUTH`, `PENDING_VERIFICATION`, `DISCONNECTED`. |
| `connected_account.token_expires_at` | string | Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. |
| `connected_account.updated_at` | string | Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. |

**Errors**

- `400`: Invalid request - missing required fields, invalid authorization details, or validation failed. Error code `RESOURCE_ALREADY_EXISTS` when the user already has a connected account on this connection; update it instead.
- `401`: Authentication required - missing or invalid access token
- `404`: Not found - no connection with this name exists in the environment. Error code `RESOURCE_NOT_FOUND`.

**Request**

```bash
curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "gmail",
    "identifier": "user_123",
    "connected_account": {
      "authorization_details": {
        "oauth_token": {
          "access_token": "[ACCESS TOKEN]",
          "refresh_token": "[REFRESH TOKEN]",
          "scopes": [
            "https://www.googleapis.com/auth/gmail.readonly"
          ]
        }
      }
    }
  }'
```

**Response**

```json
{
  "connected_account": {
    "id": "ca_24834495392086178",
    "connection_id": "conn_70219645518265104",
    "connector": "gmail",
    "identifier": "user_123",
    "provider": "GMAIL",
    "authorization_type": "OAUTH",
    "status": "ACTIVE",
    "is_org_wide_credential": false,
    "token_expires_at": "2026-10-02T15:30:00Z",
    "last_used_at": "2026-10-02T14:31:07Z",
    "updated_at": "2026-10-02T14:30:00Z",
    "authorization_details": {
      "oauth_token": {
        "access_token": "[ACCESS TOKEN]",
        "refresh_token": "[REFRESH TOKEN]",
        "scopes": [
          "https://www.googleapis.com/auth/gmail.readonly"
        ]
      }
    }
  }
}
```

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

Create a new connected account

```python
scalekit_client.actions.create_connected_account(
    connection_name: str,
    identifier: str,
    authorization_details: Optional[Dict[str, Any]] = None,
    organization_id: Optional[str] = None,
    user_id: Optional[str] = None,
    api_config: Optional[Dict[str, Any]] = None,
) -> CreateConnectedAccountResponse
```

Example:

```python
result = scalekit_client.actions.create_connected_account(
    connection_name="gmail",
    identifier="user_123",
    authorization_details={
        "oauth_token": {
            "access_token": "[ACCESS TOKEN]",
            "refresh_token": "[REFRESH TOKEN]",
            "scopes": ["https://www.googleapis.com/auth/gmail.readonly"],
        },
    },
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `str` | Yes | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `str` | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `authorization_details` | `Optional[Dict[str, Any]]` | No | Authorization details (OAuth token or static auth) |
| `organization_id` | `Optional[str]` | No | Organization ID |
| `user_id` | `Optional[str]` | No | User ID |
| `api_config` | `Optional[Dict[str, Any]]` | No | Optional API configuration for the connected account |

Returns `CreateConnectedAccountResponse`: The created connected account details

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

Create a new connected account. This helper accepts a high-level payload and builds the underlying CreateConnectedAccount message.

```ts
scalekit.actions.createConnectedAccount(
  params: {
    connectionName: string;
    identifier: string;
    authorizationDetails: MessageInitShape<typeof CreateConnectedAccountSchema>['authorizationDetails'];
    organizationId?: string;
    userId?: string;
    apiConfig?: Record<string, unknown>;
  },
): Promise<CreateConnectedAccountResponse>
```

Example:

```ts
const result = await scalekit.actions.createConnectedAccount({
  connectionName: "gmail",
  identifier: "user_123",
  authorizationDetails: {
    details: {
      case: "oauthToken",
      value: {
        accessToken: "[ACCESS TOKEN]",
        refreshToken: "[REFRESH TOKEN]",
        scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
      },
    },
  },
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | Yes | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `string` | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `authorizationDetails` | `MessageInitShape<typeof CreateConnectedAccountSchema>['authorizationDetails']` | Yes | The user's credentials: OAuth tokens as `{ case: "oauthToken", value }`, or an API key or other static values as `{ case: "staticAuth", value }`. To have the user connect their own account instead, use `getAuthorizationLink`. |
| `organizationId` | `string` | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `userId` | `string` | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |
| `apiConfig` | `Record<string, unknown>` | No | Optional JSON configuration for connector-specific API settings such as rate limits, custom API endpoints, timeouts, or feature flags. |

Returns `Promise<CreateConnectedAccountResponse>`.

**Used in**

- [Apify Actor with per-user OAuth via Scalekit](https://docs.scalekit.com/cookbooks/apify-actor-per-user-oauth/)
- [Authorize a user](https://docs.scalekit.com/agentkit/tools/authorize/)
- [Build a daily briefing agent with Vercel AI SDK and Scalekit AgentKit](https://docs.scalekit.com/cookbooks/daily-briefing-agent/)
- [Build a Mastra agent with Scalekit AgentKit tools](https://docs.scalekit.com/cookbooks/mastra-agentkit/)
- [Build a multi-agent email triage crew with CrewAI](https://docs.scalekit.com/cookbooks/crewai-agentkit-email-triage/)
- [Build a multi-user GitHub PR summarizer agent](https://docs.scalekit.com/cookbooks/render-github-pr-summarizer/)
- [Build an agent that books meetings and drafts emails](https://docs.scalekit.com/cookbooks/schedule-meeting-and-draft-email/)
- [FastRouter + Scalekit tool calling](https://docs.scalekit.com/cookbooks/fastrouter-agentkit-tool-calling/)
- [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts/)
- [Migrate from Composio to Scalekit](https://docs.scalekit.com/agentkit/advanced/migrate-from-composio/)
- [Quickstart](https://docs.scalekit.com/agentkit/quickstart/)
- [Trace AgentKit tool calls in LangSmith](https://docs.scalekit.com/cookbooks/langsmith-tracing-agentkit/)

Also called by `scalekit_client.actions.get_or_create_connected_account` (Python), `scalekit.actions.getOrCreateConnectedAccount` (Node.js).

## Get a connected account

`GET /api/v1/connected_accounts/details`

Returns a connected account's status, connection and settings, looked up by its ID or by `connector` and `identifier`. It never includes the account's credentials. To call the app yourself with them, use [Get a connected account's credentials](https://docs.scalekit.com/agentkit/reference/connected-accounts/get-connected-account-credentials/).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connector` | string | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `id` | string | No | Unique identifier for the connected account. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `organization_id` | string | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `user_id` | string | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connected_account` | object | The connected account. |
| `connected_account.api_config` | object | Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. |
| `connected_account.authorization_type` | string (enum) | Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. One of: `OAUTH`, `API_KEY`, `BASIC_AUTH`, `BEARER_TOKEN`, `CUSTOM`, `BASIC`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connected_account.connection_id` | string | Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. |
| `connected_account.connector` | string | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_account.id` | string | Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'. |
| `connected_account.identifier` | string | Your app's ID for the user, the value passed when the account was created. |
| `connected_account.is_org_wide_credential` | boolean | Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account. |
| `connected_account.last_used_at` | string | Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. |
| `connected_account.provider` | string | The app the account connects to, such as `GMAIL` or `SLACK`. |
| `connected_account.status` | string (enum) | Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. One of: `ACTIVE`, `EXPIRED`, `PENDING_AUTH`, `PENDING_VERIFICATION`, `DISCONNECTED`. |
| `connected_account.token_expires_at` | string | Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. |
| `connected_account.updated_at` | string | Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. |

**Errors**

- `400`: Invalid request - missing required query parameters
- `401`: Authentication required - missing or invalid access token
- `404`: Connected account not found - no account matches the specified criteria

**Request**

```bash
curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts/details" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "connector=gmail" \
  --data-urlencode "identifier=user_123"
```

**Response**

```json
{
  "connected_account": {
    "id": "ca_24834495392086178",
    "connection_id": "conn_70219645518265104",
    "connector": "gmail",
    "identifier": "user_123",
    "provider": "GMAIL",
    "authorization_type": "OAUTH",
    "status": "ACTIVE",
    "is_org_wide_credential": false,
    "token_expires_at": "2026-10-02T15:30:00Z",
    "last_used_at": "2026-10-02T14:31:07Z",
    "updated_at": "2026-10-02T14:30:00Z"
  }
}
```

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

Gets a connected account without its credentials. Identify the account with `connection_name` and `identifier`, or with `connected_account_id`. To get its credentials, use `get_connected_account`.

```python
scalekit_client.actions.get_connected_account_details(
    connection_name: Optional[str] = None,
    identifier: Optional[str] = None,
    connected_account_id: Optional[str] = None,
) -> GetConnectedAccountDetailsResponse
```

Example:

```python
result = scalekit_client.actions.get_connected_account_details(
    connection_name="gmail",
    identifier="user_123",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `Optional[str]` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `connected_account_id` | `Optional[str]` | No | Scalekit connected account ID. When supplied, `connection_name` and `identifier` are ignored. |

Returns `GetConnectedAccountDetailsResponse`: The account metadata without auth credentials

**Node.js:** Call this endpoint over REST, as the example shows.

```ts
const envUrl = process.env.SCALEKIT_ENVIRONMENT_URL!;
const tokenResponse = await fetch(`${envUrl}/oauth/token`, {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.SCALEKIT_CLIENT_ID!,
    client_secret: process.env.SCALEKIT_CLIENT_SECRET!,
  }),
});
const token = (await tokenResponse.json()).access_token;

const params = new URLSearchParams({ connector: "gmail", identifier: "user_123" });
const response = await fetch(`${envUrl}/api/v1/connected_accounts/details?${params}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const result = await response.json();
```

**Used in**

- [Call any API](https://docs.scalekit.com/agentkit/tools/custom-tools/)
- [Troubleshoot connection and OAuth errors](https://docs.scalekit.com/agentkit/troubleshooting/)

## List connected accounts

`GET /api/v1/connected_accounts`

Lists the connected accounts in the environment, filtered by connection, identifier, provider or organization, with each account's status. The list doesn't include credentials; use [Get a connected account's credentials](https://docs.scalekit.com/agentkit/reference/connected-accounts/get-connected-account-credentials/) for one account. Use `next_page_token` to get the next page.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_names` | array of string | No | Filter by one or more connection names (exact match). Returns connected accounts belonging to any of the specified connections. Max 20 names per request. Cannot be combined with the `connector` field. |
| `connector` | string | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `is_org_wide_credential` | boolean | No | Set to `true` to return only the shared credential of an org-wide connection, or `false` to return only users' own accounts. Omit it to return both. |
| `organization_id` | string | No | Filter by organization ID. Returns only connected accounts associated with this organization. |
| `page_size` | integer | No | Maximum number of connected accounts to return, up to 99. Defaults to 10 when omitted or 0. |
| `page_token` | string | No | Pagination token from a previous response. Use the next_page_token value from ListConnectedAccountsResponse to fetch the next page. |
| `provider` | string | No | Return only accounts for this app, such as `GMAIL` or `SLACK`. Exact match, in capitals as the account's `provider` shows it. |
| `query` | string | No | Text search query to filter connected accounts by name, identifier, or other searchable fields. Case-insensitive. |
| `user_id` | string | No | Filter by user ID. Returns only connected accounts associated with this user. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connected_accounts` | array of object | List of connected accounts matching the filter criteria. Excludes sensitive authorization details for security. |
| `connected_accounts.authorization_type` | string (enum) | Authorization mechanism type. One of: `OAUTH`, `API_KEY`, `BASIC_AUTH`, `BEARER_TOKEN`, `CUSTOM`, `BASIC`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connected_accounts.connection_id` | string | Parent connection configuration reference. |
| `connected_accounts.connector` | string | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_accounts.id` | string | Unique connected account identifier. |
| `connected_accounts.identifier` | string | Your app's ID for the user, the value passed when the account was created. |
| `connected_accounts.is_org_wide_credential` | boolean | Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account. |
| `connected_accounts.last_used_at` | string | Last usage timestamp. |
| `connected_accounts.provider` | string | The app the account connects to, such as `GMAIL` or `SLACK`. |
| `connected_accounts.status` | string (enum) | Current connection status. One of: `ACTIVE`, `EXPIRED`, `PENDING_AUTH`, `PENDING_VERIFICATION`, `DISCONNECTED`. |
| `connected_accounts.token_expires_at` | string | Token expiration timestamp. |
| `connected_accounts.updated_at` | string | Last modification timestamp. |
| `next_page_token` | string | Pagination token for retrieving the next page. Empty if this is the last page. Pass this value to page_token in the next request. |
| `prev_page_token` | string | Pagination token for retrieving the previous page. Empty if this is the first page. Pass this value to page_token to go back. |
| `total_size` | integer | Total count of connected accounts matching the filter criteria across all pages. Use for calculating pagination. |

**Errors**

- `400`: Invalid request - occurs when query parameters are malformed or validation fails
- `401`: Authentication required - missing or invalid access token

**Request**

```bash
curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "connector=gmail" \
  --data-urlencode "identifier=user_123"
```

**Response**

```json
{
  "connected_accounts": [
    {
      "id": "ca_24834495392086178",
      "connection_id": "conn_70219645518265104",
      "connector": "gmail",
      "identifier": "user_123",
      "provider": "GMAIL",
      "authorization_type": "OAUTH",
      "status": "ACTIVE",
      "is_org_wide_credential": false,
      "token_expires_at": "2026-10-02T15:30:00Z",
      "last_used_at": "2026-10-02T14:31:07Z",
      "updated_at": "2026-10-02T14:30:00Z"
    }
  ],
  "next_page_token": "",
  "prev_page_token": "",
  "total_size": 1
}
```

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

List connected accounts with optional filtering.

```python
scalekit_client.actions.list_connected_accounts(
    connection_name: Optional[str] = None,
    identifier: Optional[str] = None,
    provider: Optional[str] = None,
    connection_names: Optional[List[str]] = None,
) -> ListConnectedAccountsResponse
```

Example:

```python
result = scalekit_client.actions.list_connected_accounts(
    connection_name="gmail",
    identifier="user_123",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `Optional[str]` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `provider` | `Optional[str]` | No | Return only accounts for this app, such as `GMAIL` or `SLACK`. Exact match, in capitals as the account's `provider` shows it. |
| `connection_names` | `Optional[List[str]]` | No | Connection names, exact match. Returns accounts on any of them, such as `["gmail", "github-connect"]`. Combine with `identifier` for one user. |

Returns `ListConnectedAccountsResponse`: The matching connected accounts.

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

List connected accounts with optional filters.

```ts
scalekit.actions.listConnectedAccounts(
  params?: {
    connectionName?: string;
    identifier?: string;
    provider?: string;
    organizationId?: string;
    userId?: string;
    pageSize?: number;
    pageToken?: string;
    query?: string;
    connectionNames?: string[];
  },
): Promise<ListConnectedAccountsResponse>
```

Example:

```ts
const result = await scalekit.actions.listConnectedAccounts({
  connectionName: "gmail",
  identifier: "user_123",
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `string` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `provider` | `string` | No | Return only accounts for this app, such as `GMAIL` or `SLACK`. Exact match, in capitals as the account's `provider` shows it. |
| `organizationId` | `string` | No | Filter by organization ID. Returns only connected accounts associated with this organization. |
| `userId` | `string` | No | Filter by user ID. Returns only connected accounts associated with this user. |
| `pageSize` | `number` | No | Maximum number of connected accounts to return, up to 99. Defaults to 10 when omitted or 0. |
| `pageToken` | `string` | No | Pagination token from a previous response. Use the next_page_token value from ListConnectedAccountsResponse to fetch the next page. |
| `query` | `string` | No | Text search query to filter connected accounts by name, identifier, or other searchable fields. Case-insensitive. |
| `connectionNames` | `string[]` | No | Filter by one or more connection names (exact match). Returns connected accounts belonging to any of the specified connections. Max 20 names per request. Cannot be combined with the `connector` field. |

Returns `Promise<ListConnectedAccountsResponse>`.

**Used in**

- [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts/)

## Search connected accounts

`GET /api/v1/connected_accounts:search`

Search for connected accounts in your environment using a text query that matches against identifiers, providers, or connectors. The search performs case-insensitive matching across account details. Returns paginated results with account status and authentication type information.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search term to match against connected account identifiers, providers, or connectors. Must be at least 3 characters. Case insensitive. |
| `connection_id` | string | No | Connection ID to filter connected accounts. |
| `page_size` | integer | No | Maximum number of connected accounts to return per page. Value must be between 1 and 30. |
| `page_token` | string | No | Token from a previous response for pagination. Provide this to retrieve the next page of results. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connected_accounts` | array of object | List of connected accounts matching the search query. Excludes sensitive authorization details. |
| `connected_accounts.authorization_type` | string (enum) | Authorization mechanism type. One of: `OAUTH`, `API_KEY`, `BASIC_AUTH`, `BEARER_TOKEN`, `CUSTOM`, `BASIC`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connected_accounts.connection_id` | string | Parent connection configuration reference. |
| `connected_accounts.connector` | string | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_accounts.id` | string | Unique connected account identifier. |
| `connected_accounts.identifier` | string | Your app's ID for the user, the value passed when the account was created. |
| `connected_accounts.is_org_wide_credential` | boolean | Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account. |
| `connected_accounts.last_used_at` | string | Last usage timestamp. |
| `connected_accounts.provider` | string | The app the account connects to, such as `GMAIL` or `SLACK`. |
| `connected_accounts.status` | string (enum) | Current connection status. One of: `ACTIVE`, `EXPIRED`, `PENDING_AUTH`, `PENDING_VERIFICATION`, `DISCONNECTED`. |
| `connected_accounts.token_expires_at` | string | Token expiration timestamp. |
| `connected_accounts.updated_at` | string | Last modification timestamp. |
| `next_page_token` | string | Pagination token for the next page. Empty if this is the last page. |
| `prev_page_token` | string | Pagination token for the previous page. Empty if this is the first page. |
| `total_size` | integer | Total count of accounts matching the search query across all pages. |

**Errors**

- `400`: Invalid request - query parameter is too short (minimum 3 characters) or validation failed
- `401`: Authentication required - missing or invalid access token

**Request**

```bash
curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts:search" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "query=user_123"
```

**Response**

```json
{
  "connected_accounts": [
    {
      "id": "ca_24834495392086178",
      "connection_id": "conn_70219645518265104",
      "connector": "gmail",
      "identifier": "user_123",
      "provider": "GMAIL",
      "authorization_type": "OAUTH",
      "status": "ACTIVE",
      "is_org_wide_credential": false,
      "token_expires_at": "2026-10-02T15:30:00Z",
      "last_used_at": "2026-10-02T14:31:07Z",
      "updated_at": "2026-10-02T14:30:00Z"
    }
  ],
  "next_page_token": "",
  "prev_page_token": "",
  "total_size": 1
}
```

**Python:** Call this endpoint over REST, as the example shows.

```python
import os

import requests

env_url = os.environ["SCALEKIT_ENVIRONMENT_URL"]
token = requests.post(
    f"{env_url}/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["SCALEKIT_CLIENT_ID"],
        "client_secret": os.environ["SCALEKIT_CLIENT_SECRET"],
    },
).json()["access_token"]

response = requests.get(
    f"{env_url}/api/v1/connected_accounts:search",
    headers={"Authorization": f"Bearer {token}"},
    params={"query": "user_123"},
)
response.raise_for_status()
result = response.json()
```

**Node.js:** Call this endpoint over REST, as the example shows.

```ts
const envUrl = process.env.SCALEKIT_ENVIRONMENT_URL!;
const tokenResponse = await fetch(`${envUrl}/oauth/token`, {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.SCALEKIT_CLIENT_ID!,
    client_secret: process.env.SCALEKIT_CLIENT_SECRET!,
  }),
});
const token = (await tokenResponse.json()).access_token;

const params = new URLSearchParams({ query: "user_123" });
const response = await fetch(`${envUrl}/api/v1/connected_accounts:search?${params}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const result = await response.json();
```

## Update a connected account

`PUT /api/v1/connected_accounts`

Updates authentication credentials and configuration for an existing connected account. Modify OAuth tokens, refresh tokens, access scopes, or API configuration settings. Specify the account by ID, or by combination of organization/user, connector, and identifier. Returns the updated account with new token expiry and status information.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connected_account` | object | Yes | Details of the connected account to update. |
| `connected_account.api_config` | object | No | Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. |
| `connected_account.authorization_details` | object | No | Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. |
| `connected_account.authorization_details.google_dwd` | object | No | Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. Send only subject in requests; access_token, scopes, and token_expires_at are response-only. |
| `connected_account.authorization_details.oauth_token` | object | No | OAuth 2.0 credentials. |
| `connected_account.authorization_details.static_auth` | object | No | Static credentials, such as an API key. |
| `connected_account.authorization_details.trusted_idp` | object | No | Credentials for a connection that signs in through a trusted identity provider, such as AWS Redshift. Send only `db_user`. Responses include `access_key_id` and `expiry`, never the secret key or session token. |
| `connector` | string | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `id` | string | No | Unique identifier for the connected account to update. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `organization_id` | string | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `user_id` | string | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connected_account` | object | The updated connected account with refreshed credentials, new token expiry, and modified configuration settings. |
| `connected_account.api_config` | object | Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. |
| `connected_account.authorization_details` | object | The account's credentials. Set the one that matches the connection's auth type - `oauth_token`, `static_auth`, `google_dwd` or `trusted_idp`. |
| `connected_account.authorization_details.google_dwd` | object | Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. Send only subject in requests; access_token, scopes, and token_expires_at are response-only. |
| `connected_account.authorization_details.oauth_token` | object | OAuth 2.0 credentials. |
| `connected_account.authorization_details.static_auth` | object | Static credentials, such as an API key. |
| `connected_account.authorization_details.trusted_idp` | object | Credentials for a connection that signs in through a trusted identity provider, such as AWS Redshift. Send only `db_user`. Responses include `access_key_id` and `expiry`, never the secret key or session token. |
| `connected_account.authorization_type` | string (enum) | Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. One of: `OAUTH`, `API_KEY`, `BASIC_AUTH`, `BEARER_TOKEN`, `CUSTOM`, `BASIC`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connected_account.connection_id` | string | Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. |
| `connected_account.connector` | string | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_account.id` | string | Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'. |
| `connected_account.identifier` | string | Your app's ID for the user, the value passed when the account was created. |
| `connected_account.is_org_wide_credential` | boolean | Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account. |
| `connected_account.last_used_at` | string | Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. |
| `connected_account.provider` | string | The app the account connects to, such as `GMAIL` or `SLACK`. |
| `connected_account.status` | string (enum) | Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. One of: `ACTIVE`, `EXPIRED`, `PENDING_AUTH`, `PENDING_VERIFICATION`, `DISCONNECTED`. |
| `connected_account.token_expires_at` | string | Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. |
| `connected_account.updated_at` | string | Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. |

**Errors**

- `400`: Invalid request - missing required fields, invalid authorization details, or validation failed
- `401`: Authentication required - missing or invalid access token
- `404`: Connected account not found - the specified account does not exist

**Request**

```bash
curl -sS -X PUT \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "gmail",
    "identifier": "user_123",
    "connected_account": {
      "authorization_details": {
        "oauth_token": {
          "access_token": "[NEW ACCESS TOKEN]",
          "refresh_token": "[NEW REFRESH TOKEN]",
          "scopes": [
            "https://www.googleapis.com/auth/gmail.readonly"
          ]
        }
      }
    }
  }'
```

**Response**

```json
{
  "connected_account": {
    "id": "ca_24834495392086178",
    "connection_id": "conn_70219645518265104",
    "connector": "gmail",
    "identifier": "user_123",
    "provider": "GMAIL",
    "authorization_type": "OAUTH",
    "status": "ACTIVE",
    "is_org_wide_credential": false,
    "token_expires_at": "2026-10-02T15:30:00Z",
    "last_used_at": "2026-10-02T14:31:07Z",
    "updated_at": "2026-10-02T14:30:00Z",
    "authorization_details": {
      "oauth_token": {
        "access_token": "[NEW ACCESS TOKEN]",
        "refresh_token": "[NEW REFRESH TOKEN]",
        "scopes": [
          "https://www.googleapis.com/auth/gmail.readonly"
        ]
      }
    }
  }
}
```

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

Update an existing connected account

```python
scalekit_client.actions.update_connected_account(
    connection_name: str,
    identifier: str,
    authorization_details: Optional[Dict[str, Any]] = None,
    organization_id: Optional[str] = None,
    user_id: Optional[str] = None,
    connected_account_id: Optional[str] = None,
    api_config: Optional[Dict[str, Any]] = None,
) -> UpdateConnectedAccountResponse
```

Example:

```python
result = scalekit_client.actions.update_connected_account(
    connection_name="gmail",
    identifier="user_123",
    authorization_details={
        "oauth_token": {
            "access_token": "[NEW ACCESS TOKEN]",
            "refresh_token": "[NEW REFRESH TOKEN]",
            "scopes": ["https://www.googleapis.com/auth/gmail.readonly"],
        },
    },
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `str` | Yes | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `str` | Yes | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `authorization_details` | `Optional[Dict[str, Any]]` | No | Authorization details (OAuth token or static auth) |
| `organization_id` | `Optional[str]` | No | Organization ID |
| `user_id` | `Optional[str]` | No | User ID |
| `connected_account_id` | `Optional[str]` | No | Connected account ID |
| `api_config` | `Optional[Dict[str, Any]]` | No | Optional API configuration for the connected account |

Returns `UpdateConnectedAccountResponse`: The updated connected account details

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

Update an existing connected account. Requires either `connectedAccountId` or both `connectionName` + `identifier`.

```ts
scalekit.actions.updateConnectedAccount(
  params: {
    connectionName?: string;
    identifier?: string;
    authorizationDetails?: UpdateConnectedAccount['authorizationDetails'];
    organizationId?: string;
    userId?: string;
    connectedAccountId?: string;
    apiConfig?: UpdateConnectedAccount['apiConfig'];
  },
): Promise<UpdateConnectedAccountResponse>
```

Example:

```ts
const result = await scalekit.actions.updateConnectedAccount({
  connectionName: "gmail",
  identifier: "user_123",
  authorizationDetails: {
    details: {
      case: "oauthToken",
      value: {
        accessToken: "[NEW ACCESS TOKEN]",
        refreshToken: "[NEW REFRESH TOKEN]",
        scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
      },
    },
  },
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `string` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `authorizationDetails` | `UpdateConnectedAccount['authorizationDetails']` | No | Updated authentication credentials. Provide new OAuth tokens (e.g., after refresh) or updated static auth details. Only included fields will be modified. |
| `organizationId` | `string` | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `userId` | `string` | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |
| `connectedAccountId` | `string` | No | Unique identifier for the connected account to update |
| `apiConfig` | `UpdateConnectedAccount['apiConfig']` | No | Updated JSON configuration for API-specific settings. Merges with existing configuration - only provided fields are modified. |

Returns `Promise<UpdateConnectedAccountResponse>`.

Also called by `scalekit_client.actions.get_or_create_connected_account` (Python), `scalekit.actions.getOrCreateConnectedAccount` (Node.js).

## Get a connected account's credentials

`GET /api/v1/connected_accounts/auth`

Returns a connected account with its credentials, the user's OAuth tokens or the API key or other values they entered, so you can call the app yourself. If the OAuth access token has expired, Scalekit refreshes it first. Scalekit returns credentials only when credential access is turned on for your environment; to turn it on, contact Scalekit support. Until then, the response is the same as [Get a connected account](https://docs.scalekit.com/agentkit/reference/connected-accounts/get-a-connected-account/), with no `authorization_details`.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connector` | string | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `id` | string | No | Unique identifier for the connected account. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `organization_id` | string | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `user_id` | string | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `connected_account` | object | The connected account. |
| `connected_account.api_config` | object | Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags. |
| `connected_account.authorization_details` | object | The account's credentials, in the shape for its auth type. Returned only when credential access is turned on for your environment. |
| `connected_account.authorization_details.google_dwd` | object | Google Domain-Wide Delegation authentication — used for GOOGLE_DWD connections. Send only subject in requests; access_token, scopes, and token_expires_at are response-only. |
| `connected_account.authorization_details.oauth_token` | object | OAuth 2.0 credentials. |
| `connected_account.authorization_details.static_auth` | object | Static credentials, such as an API key. |
| `connected_account.authorization_details.trusted_idp` | object | Credentials for a connection that signs in through a trusted identity provider, such as AWS Redshift. Send only `db_user`. Responses include `access_key_id` and `expiry`, never the secret key or session token. |
| `connected_account.authorization_type` | string (enum) | Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods. One of: `OAUTH`, `API_KEY`, `BASIC_AUTH`, `BEARER_TOKEN`, `CUSTOM`, `BASIC`, `OAUTH_M2M`, `TRELLO_OAUTH1`, `GOOGLE_DWD`, `TRUSTED_IDP`, `SMART_FHIR`, `NO_AUTH`. |
| `connected_account.connection_id` | string | Reference to the parent connection configuration. Links this account to a specific connector setup in your environment. |
| `connected_account.connector` | string | The connection name, as shown in **AgentKit** > **Connections**. |
| `connected_account.id` | string | Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'. |
| `connected_account.identifier` | string | Your app's ID for the user, the value passed when the account was created. |
| `connected_account.is_org_wide_credential` | boolean | Whether this is the shared credential of an org-wide connection, which every user's tool calls on that connection use. `false` for a user's own account. |
| `connected_account.last_used_at` | string | Timestamp when this connected account was last used to make an API call. Useful for tracking active connections. |
| `connected_account.provider` | string | The app the account connects to, such as `GMAIL` or `SLACK`. |
| `connected_account.status` | string (enum) | Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification. One of: `ACTIVE`, `EXPIRED`, `PENDING_AUTH`, `PENDING_VERIFICATION`, `DISCONNECTED`. |
| `connected_account.token_expires_at` | string | Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized. |
| `connected_account.updated_at` | string | Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes. |

**Errors**

- `400`: Invalid request - missing required query parameters
- `401`: Authentication required - missing or invalid access token
- `404`: Connected account not found - no account matches the specified criteria

**Request**

```bash
curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts/auth" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "connector=gmail" \
  --data-urlencode "identifier=user_123"
```

**Response**

```json
{
  "connected_account": {
    "id": "ca_24834495392086178",
    "connection_id": "conn_70219645518265104",
    "connector": "gmail",
    "identifier": "user_123",
    "provider": "GMAIL",
    "authorization_type": "OAUTH",
    "status": "ACTIVE",
    "is_org_wide_credential": false,
    "token_expires_at": "2026-10-02T15:30:00Z",
    "last_used_at": "2026-10-02T14:31:07Z",
    "updated_at": "2026-10-02T14:30:00Z",
    "authorization_details": {
      "oauth_token": {
        "access_token": "[ACCESS TOKEN]",
        "refresh_token": "[REFRESH TOKEN]",
        "scopes": [
          "https://www.googleapis.com/auth/gmail.readonly"
        ]
      }
    }
  }
}
```

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

Get connected account authorization details by identifier

```python
scalekit_client.actions.get_connected_account(
    connection_name: Optional[str] = None,
    identifier: Optional[str] = None,
    connected_account_id: Optional[str] = None,
) -> GetConnectedAccountAuthResponse
```

Example:

```python
result = scalekit_client.actions.get_connected_account(
    connection_name="gmail",
    identifier="user_123",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `Optional[str]` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `connected_account_id` | `Optional[str]` | No | Connected account ID |

Returns `GetConnectedAccountAuthResponse`: The connected account details

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

Get connected account authorization details. Requires either `connectedAccountId` or both `connectionName` + `identifier`.

```ts
scalekit.actions.getConnectedAccount(
  params: {
    connectionName?: string;
    identifier?: string;
    connectedAccountId?: string;
    organizationId?: string;
    userId?: string;
  },
): Promise<GetConnectedAccountByIdentifierResponse>
```

Example:

```ts
const result = await scalekit.actions.getConnectedAccount({
  connectionName: "gmail",
  identifier: "user_123",
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `string` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `connectedAccountId` | `string` | No | Unique identifier for the connected account |
| `organizationId` | `string` | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `userId` | `string` | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |

Returns `Promise<GetConnectedAccountByIdentifierResponse>`.

**Used in**

- [Build a multi-user GitHub PR summarizer agent](https://docs.scalekit.com/cookbooks/render-github-pr-summarizer/)
- [Build an agent that books meetings and drafts emails](https://docs.scalekit.com/cookbooks/schedule-meeting-and-draft-email/)
- [Call any API](https://docs.scalekit.com/agentkit/tools/custom-tools/)
- [Quickstart](https://docs.scalekit.com/agentkit/quickstart/)
- [Troubleshoot connection and OAuth errors](https://docs.scalekit.com/agentkit/troubleshooting/)

Also called by `scalekit_client.actions.get_or_create_connected_account` (Python), `scalekit.actions.getOrCreateConnectedAccount` (Node.js).

## Delete a connected account

`POST /api/v1/connected_accounts:delete`

Deletes the account and the credentials Scalekit stores for it. It doesn't revoke the user's grant at the app. Identify the account by ID, or by its connector and identifier. This can't be undone.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `connector` | string | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `id` | string | No | Unique identifier for the connected account to delete. |
| `identifier` | string | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `organization_id` | string | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `user_id` | string | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |

**Errors**

- `400`: Invalid request - malformed parameters or validation failed. Error code `MCP_SERVER_EXISTS_FOR_CONNECTED_ACCOUNT` when a Virtual MCP server instance for this user still uses the account; delete that Virtual MCP server first.
- `401`: Authentication required - missing or invalid access token
- `404`: Connected account not found - the specified account does not exist

**Request**

```bash
curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts:delete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "gmail",
    "identifier": "user_123"
  }'
```

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

Delete a connected account

```python
scalekit_client.actions.delete_connected_account(
    connection_name: Optional[str] = None,
    identifier: Optional[str] = None,
    connected_account_id: Optional[str] = None,
) -> DeleteConnectedAccountResponse
```

Example:

```python
result = scalekit_client.actions.delete_connected_account(
    connection_name="gmail",
    identifier="user_123",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connection_name` | `Optional[str]` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `Optional[str]` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `connected_account_id` | `Optional[str]` | No | Connected account ID |

Returns `DeleteConnectedAccountResponse`: An empty response.

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

Delete a connected account. Requires either `connectedAccountId` or both `connectionName` + `identifier`.

```ts
scalekit.actions.deleteConnectedAccount(
  params: {
    connectionName?: string;
    identifier?: string;
    connectedAccountId?: string;
    organizationId?: string;
    userId?: string;
  },
): Promise<DeleteConnectedAccountResponse>
```

Example:

```ts
const result = await scalekit.actions.deleteConnectedAccount({
  connectionName: "gmail",
  identifier: "user_123",
});
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `connectionName` | `string` | No | The connection name, as shown in **AgentKit** > **Connections**. |
| `identifier` | `string` | No | Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address. |
| `connectedAccountId` | `string` | No | Unique identifier for the connected account to delete |
| `organizationId` | `string` | No | An organization ID to key the account by instead of `identifier`, such as a Scalekit organization ID. Ignored when `identifier` is set. |
| `userId` | `string` | No | A user ID that, with `organization_id`, keys the account to one user in that organization. Ignored when `identifier` is set. |

Returns `Promise<DeleteConnectedAccountResponse>`.

**Used in**

- [Manage connected accounts](https://docs.scalekit.com/agentkit/connected-accounts/)


---

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