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.

This page as markdown Connected accounts overview

Authorization

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

Body

connected_accountobjectrequired

Details of the connected account to create

Show 2 child attributes

api_configobject

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

authorization_detailsobject

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.

Show 4 child attributes

google_dwdobject

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.

oauth_tokenobject

OAuth 2.0 credentials.

static_authobject

Static credentials, such as an API key.

trusted_idpobject

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.

connectorstringrequired

The connection name, as shown in AgentKit > Connections.

identifierstring

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_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.create_connected_account

Create a new connected account

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

Parameters

connection_namestrrequired

The connection name, as shown in AgentKit > Connections.

identifierstrrequired

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_detailsOptional[Dict[str, Any]]

Authorization details (OAuth token or static auth)

organization_idOptional[str]

Organization ID

user_idOptional[str]

User ID

api_configOptional[Dict[str, Any]]

Optional API configuration for the connected account

Returns CreateConnectedAccountResponse: The created connected account details

From scalekit-sdk-python 2.19.1.

Also called by scalekit_client.actions.get_or_create_connected_account.

scalekit.actions.createConnectedAccount

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

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

Parameters

connectionNamestringrequired

The connection name, as shown in AgentKit > Connections.

identifierstringrequired

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.

authorizationDetailsMessageInitShape<typeof CreateConnectedAccountSchema>['authorizationDetails']required

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.

organizationIdstring

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

userIdstring

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

apiConfigRecord<string, unknown>

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

Returns Promise<CreateConnectedAccountResponse>.

From @scalekit-sdk/node 2.18.0.

Also called by scalekit.actions.getOrCreateConnectedAccount.

Response 200

connected_accountobject

The newly created connected account with its unique identifier, status, and complete authorization details including access tokens.

Show 13 child attributes

api_configobject

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

authorization_detailsobject

The account's credentials. Set the one that matches the connection's auth type - oauth_token, static_auth, google_dwd or trusted_idp.

Show 4 child attributes

google_dwdobject

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.

oauth_tokenobject

OAuth 2.0 credentials.

static_authobject

Static credentials, such as an API key.

trusted_idpobject

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

401Authentication required - missing or invalid access token

404Not found - no connection with this name exists in the environment. Error code RESOURCE_NOT_FOUND.

Used in

Request

1
curl -sS -X POST \
2
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/connected_accounts" \
3
  -H "Authorization: Bearer $TOKEN" \
4
  -H "Content-Type: application/json" \
5
  -d '{
6
    "connector": "gmail",
7
    "identifier": "user_123",
8
    "connected_account": {
9
      "authorization_details": {
10
        "oauth_token": {
11
          "access_token": "[ACCESS TOKEN]",
12
          "refresh_token": "[REFRESH TOKEN]",
13
          "scopes": [
14
            "https://www.googleapis.com/auth/gmail.readonly"
15
          ]
16
        }
17
      }
18
    }
19
  }'

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"],
        },
    },
)

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"],
      },
    },
  },
});

Response 200

1
{
2
  "connected_account": {
3
    "id": "ca_24834495392086178",
4
    "connection_id": "conn_70219645518265104",
5
    "connector": "gmail",
6
    "identifier": "user_123",
7
    "provider": "GMAIL",
8
    "authorization_type": "OAUTH",
9
    "status": "ACTIVE",
10
    "is_org_wide_credential": false,
11
    "token_expires_at": "2026-10-02T15:30:00Z",
12
    "last_used_at": "2026-10-02T14:31:07Z",
13
    "updated_at": "2026-10-02T14:30:00Z",
14
    "authorization_details": {
15
      "oauth_token": {
16
        "access_token": "[ACCESS TOKEN]",
17
        "refresh_token": "[REFRESH TOKEN]",
18
        "scopes": [
19
          "https://www.googleapis.com/auth/gmail.readonly"
20
        ]
21
      }
22
    }
23
  }
24
}