Node.js SDK reference

scalekit.actions is the primary interface for AgentKit. It handles connected account management, tool execution, and proxied API calls. scalekit.tools exposes raw tool schemas for building custom adapters.

Install and initialize

npm install @scalekit-sdk/node

import { ScalekitClient } from '@scalekit-sdk/node';

const scalekit = new ScalekitClient({
  clientId: process.env.SCALEKIT_CLIENT_ID!,
  clientSecret: process.env.SCALEKIT_CLIENT_SECRET!,
  envUrl: process.env.SCALEKIT_ENV_URL!,
});

---

Actions client

Authentication

getAuthorizationLink

Generates a time-limited OAuth magic link to authorize a user’s connection.

Input schema

NameTypeRequiredDescription

connectionNamestringoptionalConnector slug (e.g. gmail)

identifierstringoptionalUser's identifier (e.g. email)

connectedAccountIdstringoptionalDirect connected account ID (ca_...)

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

statestringoptionalOpaque value passed through to the redirect URL

userVerifyUrlstringoptionalYour app's redirect URL for user verification

Response schema GetMagicLinkForConnectedAccountResponse

Field Type Description

link string OAuth magic link URL. Redirect the user here to start the authorization flow.

Example

const { link } = await scalekit.actions.getAuthorizationLink({
  connectionName: 'gmail',
  identifier: 'user@example.com',
  userVerifyUrl: 'https://your-app.com/verify',
});
// Redirect the user to link

verifyConnectedAccountUser

Verifies the user after OAuth callback. Call this from your redirect URL handler.

Input schema

NameTypeRequiredDescription

authRequestIdstringrequiredToken from the redirect URL query params

identifierstringrequiredCurrent user's identifier

Response schema VerifyConnectedAccountUserResponse

Field Type Description

postUserVerifyRedirectUrl string URL to redirect the user to after successful verification

Example

await scalekit.actions.verifyConnectedAccountUser({
  authRequestId: req.query.auth_request_id as string,
  identifier: 'user@example.com',
});

---

Connected accounts

getOrCreateConnectedAccount

Fetches an existing connected account or creates one if none exists. Use this as the default when setting up a user.

Input schema

NameTypeRequiredDescription

connectionNamestringrequiredConnector slug

identifierstringrequiredUser's identifier

authorizationDetailsobjectoptionalOAuth token or static auth details

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

apiConfigRecord<string, unknown>optionalConnector-specific options (for example scopes or static auth fields)

Response schema CreateConnectedAccountResponse

Field Type Description

connectedAccount.id string Account ID (ca_...)

connectedAccount.identifier string User's identifier

connectedAccount.provider string Provider slug

connectedAccount.status string ACTIVE, INACTIVE, or PENDING

connectedAccount.authorizationType string OAuth, API_KEY, etc.

connectedAccount.tokenExpiresAt string ISO 8601 OAuth token expiry

Example

const { connectedAccount } = await scalekit.actions.getOrCreateConnectedAccount({
  connectionName: 'gmail',
  identifier: 'user@example.com',
});
console.log(connectedAccount.id);

getConnectedAccount

Fetches auth details for a connected account. Returns sensitive credentials. Protect access to this method.

Requires connectedAccountId or connectionName + identifier.

Input schema

NameTypeRequiredDescription

connectionNamestringoptionalConnector slug. Use with identifier when you do not pass connectedAccountId.

identifierstringoptionalEnd-user or workspace identifier. Use with connectionName.

connectedAccountIdstringoptionalConnected account ID (ca_...) when resolving by ID instead of name + identifier

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

Response schema GetConnectedAccountByIdentifierResponse

Field Type Description

connectedAccount.id string Account ID (ca_...)

connectedAccount.identifier string User's identifier

connectedAccount.provider string Provider slug

connectedAccount.status string ACTIVE, INACTIVE, or PENDING

connectedAccount.authorizationType string OAuth, API_KEY, etc.

connectedAccount.authorizationDetails object Credential payload (access token, API key, etc.)

connectedAccount.tokenExpiresAt string ISO 8601 OAuth token expiry

connectedAccount.lastUsedAt string Last time this account was used

connectedAccount.updatedAt string Last update timestamp

listConnectedAccounts

Input schema

NameTypeRequiredDescription

connectionNamestringoptionalFilter by connector

identifierstringoptionalFilter by user identifier

providerstringoptionalFilter by provider

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

pageSizenumberoptionalMaximum accounts per page (server default if omitted)

pageTokenstringoptionalOpaque cursor from a previous list response

querystringoptionalFree-text search

Response schema ListConnectedAccountsResponse

Field Type Description

connectedAccounts array List of ConnectedAccountForList objects (excludes authorizationDetails)

totalSize number Total number of matching accounts

nextPageToken string Token for the next page, if any

prevPageToken string Token for the previous page, if any

createConnectedAccount

Creates a connected account with explicit auth details.

Input schema

NameTypeRequiredDescription

connectionNamestringrequiredConnector slug. Must match a connection configured in your environment.

identifierstringrequiredStable ID for this end user or workspace (email, user_id, or custom string)

authorizationDetailsobjectrequiredOAuth token payload, API key, or other credentials for this connector

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

apiConfigRecord<string, unknown>optionalConnector-specific options (for example scopes or static auth fields)

Returns CreateConnectedAccountResponse. Same shape as getOrCreateConnectedAccount.

updateConnectedAccount

Requires connectedAccountId or connectionName + identifier.

Input schema

NameTypeRequiredDescription

connectionNamestringoptionalConnector slug. Use with identifier when you do not pass connectedAccountId.

identifierstringoptionalEnd-user or workspace identifier. Use with connectionName.

connectedAccountIdstringoptionalConnected account ID (ca_...) when updating by ID instead of name + identifier

authorizationDetailsobjectoptionalReplace or merge stored credentials (OAuth tokens, API keys, etc.)

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

apiConfigobjectoptionalConnector-specific configuration to persist on the account

Returns UpdateConnectedAccountResponse.

deleteConnectedAccount

Deletes a connected account and revokes its credentials. Requires connectedAccountId or connectionName + identifier.

Input schema

NameTypeRequiredDescription

connectionNamestringoptionalConnector slug. Use with identifier when you do not pass connectedAccountId.

identifierstringoptionalEnd-user or workspace identifier. Use with connectionName.

connectedAccountIdstringoptionalConnected account ID (ca_...) when deleting by ID instead of name + identifier

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

Returns DeleteConnectedAccountResponse.

---

Tool execution

executeTool

Executes a named tool via Scalekit.

Input schema

NameTypeRequiredDescription

toolNamestringrequiredTool name (e.g. gmail_fetch_emails)

toolInputRecord<string, unknown>requiredParameters the tool expects

identifierstringoptionalUser's identifier

connectedAccountIdstringoptionalDirect connected account ID

connectorstringoptionalConnector slug

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

Response schema ExecuteToolResponse

Field Type Description

data object Tool's structured output

executionId string Unique ID for this execution

Example

const result = await scalekit.actions.executeTool({
  toolName: 'gmail_fetch_emails',
  toolInput: { maxResults: 5, label: 'UNREAD' },
  identifier: 'user@example.com',
});
const emails = result.data;

---

Proxied API calls

request

Makes a REST API call on behalf of a connected account. Scalekit injects the user’s OAuth token automatically.

Input schema

NameTypeRequiredDescription

connectionNamestringrequiredConnector slug

identifierstringrequiredUser's identifier

pathstringrequiredAPI path (e.g. /gmail/v1/users/me/messages)

methodstringoptionalHTTP method. Default: GET

queryParamsRecord<string, unknown>optionalURL query parameters appended to path

bodyunknownoptionalJSON-serializable body for POST, PUT, PATCH, or similar methods

formDataRecord<string, unknown>optionalMultipart form fields when the upstream API expects form data instead of JSON

headersRecord<string, string>optionalExtra HTTP headers merged with Scalekit-injected auth headers

timeoutMsnumberoptionalDefault: 30000

Returns AxiosResponse. Use .data, .status, and standard Axios response attributes.

Example

const response = await scalekit.actions.request({
  connectionName: 'gmail',
  identifier: 'user@example.com',
  path: '/gmail/v1/users/me/messages',
  queryParams: { maxResults: 5, q: 'is:unread' },
});
const messages = response.data.messages;

---

Tools client

scalekit.tools gives access to raw tool schemas. Use this when building a custom framework adapter or passing schemas directly to an LLM API (e.g. Anthropic, OpenAI).

listTools

Lists all tools available in your workspace.

Input schema

NameTypeRequiredDescription

filterFilteroptionalFilter by provider, identifier, or tool name

pageSizenumberoptionalMaximum tools per page (server default if omitted)

pageTokenstringoptionalOpaque cursor from a previous list response

Response schema ListToolsResponse

Field Type Description

tools array List of tool schemas (name, description, input schema)

nextPageToken string Token for the next page, if any

listScopedTools

Lists tools scoped to a specific user. Use this to fetch per-user tool schemas to pass to an LLM API.

Input schema

NameTypeRequiredDescription

identifierstringrequiredUser's connected account identifier

filterScopedToolFilteroptionalFilter by providers, tool names, or connection names

pageSizenumberoptionalMaximum tools per page (server default if omitted)

pageTokenstringoptionalOpaque cursor from a previous list response

Response schema ListScopedToolsResponse

Field Type Description

tools array List of tool schemas

tools[].name string Tool name

tools[].description string Tool description

tools[].inputSchema object JSON Schema for tool inputs. Pass directly to LLM API.

nextPageToken string Token for the next page, if any

Example

const { tools } = await scalekit.tools.listScopedTools('user@example.com', {
  filter: { connectionNames: ['gmail'] },
});
// Pass tools to your LLM's tool call API

listAvailableTools

Lists tools available for a given identifier. These tools can be activated but may not yet be scoped to the user.

Input schema

NameTypeRequiredDescription

identifierstringrequiredUser's connected account identifier

pageSizenumberoptionalMaximum tools per page (server default if omitted)

pageTokenstringoptionalOpaque cursor from a previous list response

Response schema ListAvailableToolsResponse

Field Type Description

tools array List of available tool schemas

nextPageToken string Token for the next page, if any

executeTool

Low-level tool execution. Prefer scalekit.actions.executeTool for most use cases.

Input schema

NameTypeRequiredDescription

toolNamestringrequiredRegistered tool name to execute

identifierstringoptionalEnd-user or workspace identifier used to resolve the connected account

paramsRecord<string, unknown>optionalTool arguments matching the tool input schema

connectedAccountIdstringoptionalConnected account ID (ca_...) when you already know it

connectorstringoptionalConnector slug when the tool name exists on more than one connector

organizationIdstringoptionalOrganization tenant ID when your app scopes auth and accounts by org

userIdstringoptionalYour application user ID when you map Scalekit accounts to internal users

Returns ExecuteToolResponse. Same shape as scalekit.actions.executeTool.

---

Error handling

import {
  ScalekitNotFoundException,
  ScalekitServerException,
} from '@scalekit-sdk/node';

try {
  const account = await scalekit.actions.getConnectedAccount({
    connectionName: 'gmail',
    identifier: 'user@example.com',
  });
} catch (err) {
  if (err instanceof ScalekitNotFoundException) {
    // Account does not exist: create it or redirect to auth
  } else if (err instanceof ScalekitServerException) {
    // Network or server error
    console.error(err);
  }
}

Exception	When raised
ScalekitNotFoundException	Resource not found
ScalekitUnauthorizedException	Invalid credentials
ScalekitForbiddenException	Insufficient permissions
ScalekitServerException	Base class for all server errors