> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Node.js SDK reference

Complete API reference for the Scalekit Node.js SDK: actions client and tools client.
`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

```bash
npm install @scalekit-sdk/node
```

```ts

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

- `connectionName` (`string`, optional): Connector slug (e.g. gmail)
- `identifier` (`string`, optional): User's identifier (e.g. email)
- `connectedAccountId` (`string`, optional): Direct connected account ID (ca_...)
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users
- `state` (`string`, optional): Opaque value passed through to the redirect URL
- `userVerifyUrl` (`string`, optional): Your app's redirect URL for user verification

### Response schema

Type: `GetMagicLinkForConnectedAccountResponse`

- `link` (`string`): OAuth magic link URL. Redirect the user here to start the authorization flow.

```ts title="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

- `authRequestId` (`string`, required): Token from the redirect URL query params
- `identifier` (`string`, required): Current user's identifier

### Response schema

Type: `VerifyConnectedAccountUserResponse`

- `postUserVerifyRedirectUrl` (`string`): URL to redirect the user to after successful verification

```ts title="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

- `connectionName` (`string`, required): Connector slug
- `identifier` (`string`, required): User's identifier
- `authorizationDetails` (`object`, optional): OAuth token or static auth details
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users
- `apiConfig` (`Record<string, unknown>`, optional): Connector-specific options (for example scopes or static auth fields)

### Response schema

Type: `CreateConnectedAccountResponse`

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

```ts title="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

- `connectionName` (`string`, optional): Connector slug. Use with identifier when you do not pass connectedAccountId.
- `identifier` (`string`, optional): End-user or workspace identifier. Use with connectionName.
- `connectedAccountId` (`string`, optional): Connected account ID (ca_...) when resolving by ID instead of name + identifier
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users

### Response schema

Type: `GetConnectedAccountByIdentifierResponse`

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

- `connectionName` (`string`, optional): Filter by connector
- `identifier` (`string`, optional): Filter by user identifier
- `provider` (`string`, optional): Filter by provider
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users
- `pageSize` (`number`, optional): Maximum accounts per page (server default if omitted)
- `pageToken` (`string`, optional): Opaque cursor from a previous list response
- `query` (`string`, optional): Free-text search

### Response schema

Type: `ListConnectedAccountsResponse`

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

- `connectionName` (`string`, required): Connector slug. Must match a connection configured in your environment.
- `identifier` (`string`, required): Stable ID for this end user or workspace (email, user_id, or custom string)
- `authorizationDetails` (`object`, required): OAuth token payload, API key, or other credentials for this connector
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users
- `apiConfig` (`Record<string, unknown>`, optional): Connector-specific options (for example scopes or static auth fields)

Returns CreateConnectedAccountResponse. Same shape as `getOrCreateConnectedAccount`.

#### updateConnectedAccount

Requires `connectedAccountId` **or** `connectionName` + `identifier`.

### Input schema

- `connectionName` (`string`, optional): Connector slug. Use with identifier when you do not pass connectedAccountId.
- `identifier` (`string`, optional): End-user or workspace identifier. Use with connectionName.
- `connectedAccountId` (`string`, optional): Connected account ID (ca_...) when updating by ID instead of name + identifier
- `authorizationDetails` (`object`, optional): Replace or merge stored credentials (OAuth tokens, API keys, etc.)
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users
- `apiConfig` (`object`, optional): Connector-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

- `connectionName` (`string`, optional): Connector slug. Use with identifier when you do not pass connectedAccountId.
- `identifier` (`string`, optional): End-user or workspace identifier. Use with connectionName.
- `connectedAccountId` (`string`, optional): Connected account ID (ca_...) when deleting by ID instead of name + identifier
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users

Returns DeleteConnectedAccountResponse.

---

### Tool execution

#### executeTool

Executes a named tool via Scalekit.

### Input schema

- `toolName` (`string`, required): Tool name (e.g. gmail_fetch_emails)
- `toolInput` (`Record<string, unknown>`, required): Parameters the tool expects
- `identifier` (`string`, optional): User's identifier
- `connectedAccountId` (`string`, optional): Direct connected account ID
- `connector` (`string`, optional): Connector slug
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users

### Response schema

Type: `ExecuteToolResponse`

- `data` (`object`): Tool's structured output
- `executionId` (`string`): Unique ID for this execution

```ts title="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

- `connectionName` (`string`, required): Connector slug
- `identifier` (`string`, required): User's identifier
- `path` (`string`, required): API path (e.g. /gmail/v1/users/me/messages)
- `method` (`string`, optional): HTTP method. Default: GET
- `queryParams` (`Record<string, unknown>`, optional): URL query parameters appended to path
- `body` (`unknown`, optional): JSON-serializable body for POST, PUT, PATCH, or similar methods
- `formData` (`Record<string, unknown>`, optional): Multipart form fields when the upstream API expects form data instead of JSON
- `headers` (`Record<string, string>`, optional): Extra HTTP headers merged with Scalekit-injected auth headers
- `timeoutMs` (`number`, optional): Default: 30000

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

```ts title="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

- `filter` (`Filter`, optional): Filter by provider, identifier, or tool name
- `pageSize` (`number`, optional): Maximum tools per page (server default if omitted)
- `pageToken` (`string`, optional): Opaque cursor from a previous list response

### Response schema

Type: `ListToolsResponse`

- `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 for tool discovery because it returns pagination metadata such as `nextPageToken` and `totalSize`.

### Input schema

- `identifier` (`string`, required): User's connected account identifier
- `filter` (`ScopedToolFilter`, optional): Filter by providers, tool names, or connection names
- `pageSize` (`number`, optional): Maximum tools per page. Use 100 for discovery so connectors with more than the default page are not truncated.
- `pageToken` (`string`, optional): Opaque cursor from a previous list response

### Response schema

Type: `ListScopedToolsResponse`

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

```ts title="Example"
const { tools } = await scalekit.tools.listScopedTools('user@example.com', {
  filter: { connectionNames: ['gmail'] },
  pageSize: 100,
});
// 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

- `identifier` (`string`, required): User's connected account identifier
- `pageSize` (`number`, optional): Maximum tools per page (server default if omitted)
- `pageToken` (`string`, optional): Opaque cursor from a previous list response

### Response schema

Type: `ListAvailableToolsResponse`

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

- `toolName` (`string`, required): Registered tool name to execute
- `identifier` (`string`, optional): End-user or workspace identifier used to resolve the connected account
- `params` (`Record<string, unknown>`, optional): Tool arguments matching the tool input schema
- `connectedAccountId` (`string`, optional): Connected account ID (ca_...) when you already know it
- `connector` (`string`, optional): Connector slug when the tool name exists on more than one connector
- `organizationId` (`string`, optional): Organization tenant ID when your app scopes auth and accounts by org
- `userId` (`string`, optional): Your application user ID when you map Scalekit accounts to internal users

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

---

## Error handling

```ts

  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 |


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |