Skip to content

docs: add Scalekit integration page#2570

Open
saif-at-scalekit wants to merge 10 commits into
apify:masterfrom
saif-at-scalekit:docs/add-scalekit-integration
Open

docs: add Scalekit integration page#2570
saif-at-scalekit wants to merge 10 commits into
apify:masterfrom
saif-at-scalekit:docs/add-scalekit-integration

Conversation

@saif-at-scalekit
Copy link
Copy Markdown

@saif-at-scalekit saif-at-scalekit commented May 26, 2026

Summary

Adds a Scalekit integration page to the platform documentation. Scalekit is auth infrastructure for AI agents that provides a token vault and connector layer for OAuth 2.0 flows, token storage, automatic refresh, and API proxying for 100+ third-party services.

New page contents

  • What is Scalekit — overview of the token vault and connector layer
  • Prerequisites — Scalekit account, Apify account, Node SDK install, env vars
  • Step-by-step guide:
    1. Initialize the Scalekit client
    2. Connect a user's account via getOrCreateConnectedAccount
    3. Authorize via OAuth link with polling loop
    4. Call APIs via executeTool (pre-built tools) or actions.request (direct)
  • Complete working example — full Actor code (Notion search)
  • LLM agent Actor section — using executeTool in an LLM tool-calling loop
  • Available connectors table — 14 common services with connectionName values
  • Resources — links to AgentKit docs, quickstart, connectors, example repo

Style guide alignment

  • Front matter description uses the "Learn how to..." pattern (140-160 chars)
  • Prerequisites formatted with italic item names per existing integration pages
  • Third-party disclaimer partial imported and placed after intro section
  • Follows Conventional Commits (docs: prefix)

Related

Copy link
Copy Markdown
Contributor

@marcel-rbro marcel-rbro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@saif-at-scalekit Thank you for the contribution, there are some issue in the PR that need to be resolved before we can merge it.


import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx';

## What is Scalekit
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Redundant heading. We're slowly removing these "What is XYZ" headings from our docs.

- _A configured connection_ in the Scalekit dashboard - go to **Agent Auth > Connections > + Create Connection** and select the service, for example Notion
- _Node.js 18+_

Install the Scalekit SDK in your Actor project:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The installation should be the Step 1, initialization of the client should be the 2nd step.

});
```

Both approaches use the same connected account and the same token vault. Use `executeTool` when a pre-built tool exists for your use case. Use `actions.request` for full control over the API call or to reach endpoints without a pre-built tool.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good info, but this should be in the intro to the entire Step 4 section. That way you decide which approach to use before learning about both.

Comment on lines +268 to +283
| Service | `connectionName` |
| --- | --- |
| Gmail | `gmail` |
| Google Calendar | `googlecalendar` |
| Google Drive | `googledrive` |
| Slack | `slack` |
| Notion | `notion` |
| GitHub | `github` |
| HubSpot | `hubspot` |
| Jira | `jira` |
| Salesforce | `salesforce` |
| Linear | `linear` |
| Outlook | `outlook` |
| Zoom | `zoom` |
| Gong | `gong` |
| Airtable | `airtable` |
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to list as many examples with their identifiers. For an exhaustive list, users would go to the linked documentation either way. We can just list examples of available services and navigate users to your docs for the identifiers.

- [Agentic tool calling](https://docs.scalekit.com/agentkit/tools/overview)
- [Notion + YouTube Agent example](https://github.com/scalekit-developers/agentkit-apify-actor-example)
- [Apify Actor per-user OAuth cookbook](https://docs.scalekit.com/cookbooks/apify-actor-per-user-oauth/)
- [Apify Actor documentation](/platform/actors) No newline at end of file
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing newline at the end of the file


## What is Scalekit

[Scalekit](https://scalekit.com) is auth infrastructure for AI agents. It provides a token vault and connector layer that handles OAuth 2.0 flows, token storage, automatic refresh, and API proxying for 100+ third-party services including Notion, Gmail, Slack, Google Calendar, GitHub, and more.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion from automated review:

100+ third-party services (and 100+ connectors on line 266) is the vague-qualifier pattern our style guide flags. Prefer more than 100, or use the actual count if it's stable.

If the account is not active, generate an authorization link and surface it in the Actor's status message. The user completes OAuth in their browser, and the Actor polls until the connection is active.

```javascript
import { ConnectorStatus } from '@scalekit-sdk/node/lib/pkg/grpc/scalekit/v1/connected_accounts/connected_accounts_pb';
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion from automated review:

The deep import path '@scalekit-sdk/node/lib/pkg/grpc/scalekit/v1/connected_accounts/connected_accounts_pb' reaches into the SDK's internals and is brittle if the package layout changes. Is ConnectorStatus available from a top-level export? If not, consider comparing against the string 'ACTIVE' shown in the status table on lines 82-86.

identifier: userId,
});

let account = resp.connectedAccount ?? resp;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion from automated review:

resp.connectedAccount ?? resp defensively unwraps two possible response shapes (same pattern repeats on lines 112, 191, 214). If the SDK really returns both shapes, a one-line comment explaining why would help. If it consistently returns one shape, this is dead code - simplify to either resp.connectedAccount or resp.


try {
const input = await Actor.getInput();
const { task } = input;
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion from automated review:

const { task } = input; assumes input is non-null, but Actor.getInput() can return null when the Actor runs without input. Either add a guard (if (!input) throw new Error('Input is required.')) or note in prose that input is required.


Change `connectionName` in `getOrCreateConnectedAccount` and `getAuthorizationLink` to connect to a different service. The rest of the code stays the same.

[Browse all connectors](https://docs.scalekit.com/agentkit/connectors)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion from automated review:

The orphan [Browse all connectors](...) link standing alone after the table reads like a CTA. Consider folding it into the preceding sentence: ...The rest of the code stays the same - [browse all connectors](https://docs.scalekit.com/agentkit/connectors).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants