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.

This page as markdown Connected accounts overview

Authorization

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

Query parameters

connectorstring

The connection name, as shown in AgentKit > Connections.

idstring

Unique identifier for the connected account

identifierstring

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_idstring

An organization ID to key the account by instead of identifier, such as a Scalekit organization ID. Ignored when identifier is set.

user_idstring

A user ID that, with organization_id, keys the account to one user in that organization. Ignored when identifier is set.

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.

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

Parameters

connection_nameOptional[str]

The connection name, as shown in AgentKit > Connections.

identifierOptional[str]

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_idOptional[str]

Scalekit connected account ID. When supplied, connection_name and identifier are ignored.

Returns GetConnectedAccountDetailsResponse: The account metadata without auth credentials

From scalekit-sdk-python 2.19.1.

Response 200

connected_accountobject

The connected account.

Show 12 child attributes

api_configobject

Optional JSON configuration for connector-specific API settings such as rate limits, custom endpoints, or feature flags.

authorization_typestring (enum)

Type of authorization mechanism used. Specifies whether this connection uses OAuth, API keys, bearer tokens, or other auth methods.

OAUTHAPI_KEYBASIC_AUTHBEARER_TOKENCUSTOMBASICOAUTH_M2MTRELLO_OAUTH1GOOGLE_DWDTRUSTED_IDPSMART_FHIRNO_AUTH

connection_idstring

Reference to the parent connection configuration. Links this account to a specific connector setup in your environment.

connectorstring

The connection name, as shown in AgentKit > Connections.

idstring

Unique Scalekit-generated identifier for this connected account. Always prefixed with 'ca_'.

identifierstring

Your app's ID for the user, the value passed when the account was created.

is_org_wide_credentialboolean

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.

last_used_atstring

Timestamp when this connected account was last used to make an API call. Useful for tracking active connections.

providerstring

The app the account connects to, such as GMAIL or SLACK.

statusstring (enum)

Current status of the connected account. Indicates if the account is active, expired, pending authorization, or pending user identity verification.

ACTIVEEXPIREDPENDING_AUTHPENDING_VERIFICATIONDISCONNECTED

token_expires_atstring

Expiration timestamp for the access token. After this time, the token must be refreshed or re-authorized.

updated_atstring

Timestamp when this connected account was last modified. Updated whenever credentials or configuration changes.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - missing required query parameters

401Authentication required - missing or invalid access token

404Connected account not found - no account matches the specified criteria

Used in

Request

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"

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

1
const envUrl = process.env.SCALEKIT_ENVIRONMENT_URL!;
2
const tokenResponse = await fetch(`${envUrl}/oauth/token`, {
3
  method: "POST",
4
  body: new URLSearchParams({
5
    grant_type: "client_credentials",
6
    client_id: process.env.SCALEKIT_CLIENT_ID!,
7
    client_secret: process.env.SCALEKIT_CLIENT_SECRET!,
8
  }),
9
});
10
const token = (await tokenResponse.json()).access_token;
11

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

Response 200

{
  "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"
  }
}