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_123',});listConnectedAccounts
Section titled “listConnectedAccounts”#asynclistConnectedAccounts
List connected accounts with optional filters.
Common fields: connectionName, identifier, provider, organizationId, userId, pageSize, pageToken, query. Pass connectionNames (string array) to filter to connected accounts belonging to any of the listed connections (exact match, max 20).
Paginated connected accounts.
// Optional filters: connectionName, identifier, provider, pageSize, pageTokenconst response = await scalekit.actions.listConnectedAccounts({ connectionName: 'GMAIL', identifier: 'user_123', 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. connector is the connection name, such as gmail.
Tool result and execution ID.
Pass connectedAccountId, or identifier together with connector. Don’t pass identifier on its own. When you pass connectedAccountId, Scalekit ignores identifier.
// actions.executeTool maps toolInput -> tools.executeTool paramsconst response = await scalekit.actions.executeTool({ toolName: 'gmail_fetch_mails', toolInput: { max_results: 1 }, identifier: 'user_123', 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_123', 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_123',});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_123',});// 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_123', 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_123',});// 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_123', 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_123', path: '/gmail/v1/users/me/profile', method: 'GET',});// AxiosResponse: response.status, response.data