> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents.
> Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connected accounts

Connect accounts, start auth, and execute tools with scalekit.actions
<div class="sdk-client-page">

`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](/agentkit/sdks/node/tools/). For exception types, see [Error handling](/agentkit/sdks/node/errors/).

### verifyConnectedAccountUser
<div class="sdk-method-section">
  
    
      

      Verify the connected account user after OAuth callback.

      
        Required or common fields: `authRequestId`, `identifier`.
      
      
        Post-verify redirect URL.
      

```typescript wrap showLineNumbers=false
// authRequestId: from the user-verify redirect query string
// identifier: same user identifier used when starting connect
await scalekit.actions.verifyConnectedAccountUser({
  authRequestId: 'opaque-auth-request-id',
  identifier: 'user@example.com',
});
```

    
  
</div>

### listConnectedAccounts
<div class="sdk-method-section">
  
    
      

      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.
      

```typescript wrap showLineNumbers=false
// Optional filters: connectionName, identifier, provider, pageSize, pageToken
const response = await scalekit.actions.listConnectedAccounts({
  connectionName: 'GMAIL',
  identifier: 'user@example.com',
  pageSize: 20,
});
// response.connectedAccounts, response.nextPageToken, response.totalSize
```

    
  
</div>

### executeTool
<div class="sdk-method-section">
  
    
      

      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.
      

```typescript wrap showLineNumbers=false
// actions.executeTool maps toolInput -> tools.executeTool params
const response = await scalekit.actions.executeTool({
  toolName: 'gmail_fetch_mails',
  toolInput: { max_results: 1 },
  identifier: 'user@example.com',
  connector: 'GMAIL',
});
// response.data, response.executionId
```

    
  
</div>

### getAuthorizationLink
<div class="sdk-method-section">
  
    
      

      Get an authorization magic link for a connected account.

      
        Required or common fields: `connectionName`, `identifier`, `connectedAccountId`, `organizationId`, `userId`, `state`, `userVerifyUrl`.
      
      
        Authorization magic link.
      

    

```typescript wrap showLineNumbers=false
// connectionName: app connection / connector name
// identifier: end-user identifier for the connected account
const 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 here
```

    
  
</div>

### listConnections
<div class="sdk-method-section">
  
    
      

      List app-level connections with optional pagination and provider filtering.

      
        Required or common fields: `pageSize`, `pageToken`, `provider`.
      
      
        Paginated results.
      

```typescript wrap showLineNumbers=false
// 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);
}
```

    
  
</div>

### deleteConnectedAccount
<div class="sdk-method-section">
  
    
      

      Delete a connected account.

      
        Required or common fields: `connectionName`, `identifier`, `connectedAccountId`, `organizationId`, `userId`.
      
      
        Empty on success.
      

```typescript wrap showLineNumbers=false
// Require connectedAccountId OR connectionName + identifier
await scalekit.actions.deleteConnectedAccount({
  connectionName: 'GMAIL',
  identifier: 'user@example.com',
});
```

    
  
</div>

### getConnectedAccount
<div class="sdk-method-section">
  
    
      

      Get connected account authorization details.

      
        Required or common fields: `connectionName`, `identifier`, `connectedAccountId`, `organizationId`, `userId`.
      
      
        The response payload for this operation.
      

```typescript wrap showLineNumbers=false
// Returns authorization details (sensitive). Prefer details-only APIs when available.
const response = await scalekit.actions.getConnectedAccount({
  connectionName: 'GMAIL',
  identifier: 'user@example.com',
});
// response.connectedAccount
```

    
  
</div>

### createConnectedAccount
<div class="sdk-method-section">
  
    
      

      Create a new connected account.

      
        Required or common fields: `connectionName`, `identifier`, `authorizationDetails`, `organizationId`, `userId`, `apiConfig`.
      
      
        The created resource.
      

```typescript wrap showLineNumbers=false
// 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.connectedAccount
```

    
  
</div>

### getOrCreateConnectedAccount
<div class="sdk-method-section">
  
    
      

      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.
      

```typescript wrap showLineNumbers=false
// Upsert: creates when missing; authorizationDetails optional
const response = await scalekit.actions.getOrCreateConnectedAccount({
  connectionName: 'GMAIL',
  identifier: 'user@example.com',
});
// response.connectedAccount
// Alias: scalekit.actions.upsertConnectedAccount(...)
```

    
  
</div>

### updateConnectedAccount
<div class="sdk-method-section">
  
    
      

      Update an existing connected account.

      
        Required or common fields: `connectionName`, `identifier`, `authorizationDetails`, `organizationId`, `userId`, `connectedAccountId`, `apiConfig`.
      
      
        The updated resource.
      

```typescript wrap showLineNumbers=false
// Require connectedAccountId OR connectionName + identifier
const response = await scalekit.actions.updateConnectedAccount({
  connectionName: 'GMAIL',
  identifier: 'user@example.com',
  apiConfig: {
    version: 'v1.0',
    domain: 'gmail.com',
  },
});
// response.connectedAccount
```

    
  
</div>

### request
<div class="sdk-method-section">
  
    
      

      Make a proxied REST API call on behalf of a connected account.

      
        timeoutMs: Per-call request timeout in ms.
      
      
        AxiosResponse(any)
      

```typescript wrap showLineNumbers=false
// Proxied HTTP: {envUrl}/proxy{path} with connection_name + identifier headers
const response = await scalekit.actions.request({
  connectionName: 'GMAIL',
  identifier: 'user@example.com',
  path: '/gmail/v1/users/me/profile',
  method: 'GET',
});
// AxiosResponse: response.status, response.data
```

    
  
</div>

</div>


---

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