Connected accounts
Connect accounts, start auth, and execute tools with scalekit.actions
scalekit.actions is the primary AgentKit client for connecting end-user accounts, starting OAuth, and executing tools on their behalf.
Common path: create or look up a connected account → get an authorization link → verify the user after redirect → run tools with executeTool.
For raw tool schemas used by custom adapters, see Tool calling. For exception types, see Error handling.
verifyConnectedAccountUser
Section titled “verifyConnectedAccountUser”#asyncverifyConnectedAccountUser
Verify the connected account user after OAuth callback.
Required or common fields: authRequestId, identifier.
Post-verify redirect URL.
// authRequestId: from the user-verify redirect query string// identifier: same user identifier used when starting connectawait scalekit.actions.verifyConnectedAccountUser({ authRequestId: 'opaque-auth-request-id', identifier: 'user@example.com',});listConnectedAccounts
Section titled “listConnectedAccounts”#asynclistConnectedAccounts
List connected accounts with optional filters.
Required or common fields: connectionName, identifier, provider, organizationId, userId, pageSize, pageToken, query.
Paginated connected accounts.
// Optional filters: connectionName, identifier, provider, pageSize, pageTokenconst response = await scalekit.actions.listConnectedAccounts({ connectionName: 'GMAIL', identifier: 'user@example.com', pageSize: 20,});// response.connectedAccounts, response.nextPageToken, response.totalSizeexecuteTool
Section titled “executeTool”#asyncexecuteTool
Execute a tool on behalf of a connected account.
Required or common fields: toolName, toolInput, identifier, connectedAccountId, connector, organizationId, userId.
Tool result and execution ID.
// actions.executeTool maps toolInput -> tools.executeTool paramsconst response = await scalekit.actions.executeTool({ toolName: 'gmail_fetch_mails', toolInput: { max_results: 1 }, identifier: 'user@example.com', connector: 'GMAIL',});// response.data, response.executionIdgetAuthorizationLink
Section titled “getAuthorizationLink”#asyncgetAuthorizationLink
Get an authorization magic link for a connected account.
Required or common fields: connectionName, identifier, connectedAccountId, organizationId, userId, state, userVerifyUrl.
Authorization magic link.
// connectionName: app connection / connector name// identifier: end-user identifier for the connected accountconst response = await scalekit.actions.getAuthorizationLink({ connectionName: 'GMAIL', identifier: 'user@example.com', state: 'csrf-token-abc123', userVerifyUrl: 'https://yourapp.com/auth/callback',});// response.link — redirect the user herelistConnections
Section titled “listConnections”#asynclistConnections
List app-level connections with optional pagination and provider filtering.
Required or common fields: pageSize, pageToken, provider.
Paginated results.
// App-level AgentKit connections (not SSO org connections)const { connections, nextPageToken, totalSize } = await scalekit.actions.listConnections({ pageSize: 30, provider: 'GMAIL', // optional; case-sensitive provider key });
for (const conn of connections) { console.log(conn.id, conn.connectionName, conn.status, conn.enabled);}deleteConnectedAccount
Section titled “deleteConnectedAccount”#asyncdeleteConnectedAccount
Delete a connected account.
Required or common fields: connectionName, identifier, connectedAccountId, organizationId, userId.
Empty on success.
// Require connectedAccountId OR connectionName + identifierawait scalekit.actions.deleteConnectedAccount({ connectionName: 'GMAIL', identifier: 'user@example.com',});getConnectedAccount
Section titled “getConnectedAccount”#asyncgetConnectedAccount
Get connected account authorization details.
Required or common fields: connectionName, identifier, connectedAccountId, organizationId, userId.
The response payload for this operation.
// Returns authorization details (sensitive). Prefer details-only APIs when available.const response = await scalekit.actions.getConnectedAccount({ connectionName: 'GMAIL', identifier: 'user@example.com',});// response.connectedAccountcreateConnectedAccount
Section titled “createConnectedAccount”#asynccreateConnectedAccount
Create a new connected account.
Required or common fields: connectionName, identifier, authorizationDetails, organizationId, userId, apiConfig.
The created resource.
// authorizationDetails required. Shape matches AuthorizationDetails (oauthToken | staticAuth).// Tests build it with @bufbuild/protobuf create() + AuthorizationDetailsSchema / OauthTokenSchema// from the generated connected_accounts protobuf module.const response = await scalekit.actions.createConnectedAccount({ connectionName: 'GMAIL', identifier: 'user@example.com', authorizationDetails: { details: { case: 'oauthToken', value: { accessToken: process.env.PROVIDER_ACCESS_TOKEN!, }, }, },});// response.connectedAccountgetOrCreateConnectedAccount
Section titled “getOrCreateConnectedAccount”#asyncgetOrCreateConnectedAccount
Get an existing connected account or create a new one if it doesn’t exist.
Required or common fields: connectionName, identifier, authorizationDetails, organizationId, userId, apiConfig.
The response payload for this operation.
// Upsert: creates when missing; authorizationDetails optionalconst response = await scalekit.actions.getOrCreateConnectedAccount({ connectionName: 'GMAIL', identifier: 'user@example.com',});// response.connectedAccount// Alias: scalekit.actions.upsertConnectedAccount(...)updateConnectedAccount
Section titled “updateConnectedAccount”#asyncupdateConnectedAccount
Update an existing connected account.
Required or common fields: connectionName, identifier, authorizationDetails, organizationId, userId, connectedAccountId, apiConfig.
The updated resource.
// Require connectedAccountId OR connectionName + identifierconst response = await scalekit.actions.updateConnectedAccount({ connectionName: 'GMAIL', identifier: 'user@example.com', apiConfig: { version: 'v1.0', domain: 'gmail.com', },});// response.connectedAccountrequest
Section titled “request”#asyncrequest
Make a proxied REST API call on behalf of a connected account.
timeoutMs: Per-call request timeout in ms.
AxiosResponse(any)
// Proxied HTTP: {envUrl}/proxy{path} with connection_name + identifier headersconst response = await scalekit.actions.request({ connectionName: 'GMAIL', identifier: 'user@example.com', path: '/gmail/v1/users/me/profile', method: 'GET',});// AxiosResponse: response.status, response.data