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

---

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


Part of [Connected accounts](https://docs.scalekit.com/agentkit/reference/connected-accounts/) 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 |