How AgentKit works

You configure a connection once per app. Each user approves access once, which activates their connected account. After that, your agent calls tools with the user’s identifier, and Scalekit makes the API call with that user’s token.

1. Once per app1 · You set up a connectionin the dashboard
2. Once per user2 · Your user approves accessauthorization link
3. Scalekit3 · Scalekit stores tokensconnected account is ACTIVE once any user verification passes
4. Every tool call4 · Your agent calls a toolidentifier + tool name

Gmail, Slack, GitHub…API call with the user's tokenScalekit adds the token, calls the API and returns JSON to your agent.

Term	What it is	Who creates it	In code
Connector	A supported app, such as Gmail, and its library of tools.	Scalekit, or you for a custom connector	gmail
Connection	Your environment’s settings for one connector: an OAuth client and scopes, or the fields for API-key sign-in. All your users share it.	You, once, in the dashboard	connection_name
Connected account	One user’s link to a connection. It holds their tokens and a status.	Your code creates it. The user activates it by approving access.	connected_account_id
Identifier	Your app’s ID for the user. Always pass it with the connection name.	You	identifier
Authorization link	A one-time URL where the user approves access.	Scalekit, when your code asks for one	get_authorization_link
User verification	The check that the person who approved access is the user you meant.	Your server, or Scalekit	verify_connected_account_user
Tool	One action on a connector, with an input schema.	Scalekit for built-in tools, or you for custom tools	tool_name
Virtual MCP server	A URL that exposes chosen tools for one user to any MCP client.	You, per agent	actions.mcp
Session token	A short-lived bearer token that lets an MCP client call a Virtual MCP server’s tools as one user. Mint one before each run.	Your server, per run	actions.mcp.create_session_token
API proxy	A call to the app’s own API through Scalekit, which adds the user’s credentials. Use it when no built-in tool fits. See Call any API.	Your code	actions.request

The In code column shows Python names. The Node.js SDK uses the camelCase form, such as connectionName and connectedAccountId. One exception: Node.js executeTool takes the connection name as connector and the tool’s inputs as toolInput. The REST API also names the connection connector.

Status	Means	What to do
ACTIVE	Tokens are valid.	Call tools.
PENDING_AUTH	The user hasn’t finished approving access.	Send a new authorization link.
PENDING_VERIFICATION	The user approved, but user verification hasn’t confirmed them.	Finish your verify step, or check the verification mode.
EXPIRED	Tokens expired or were revoked and couldn’t be refreshed.	Send a new authorization link.
DISCONNECTED	The account was disconnected.	Reconnect with a new authorization link.

In Python, status is a string such as "ACTIVE". In Node.js, it is the numeric ConnectorStatus enum: import it from @scalekit-sdk/node (2.18.0 or later) and compare with ConnectorStatus.ACTIVE. The REST API returns the name as a string.

Use your app’s internal user ID. It must be stable (it never changes), unique per user and hard to guess. Don’t use an email address: a user can change their email, and an old address can be reassigned to someone else, so the identifier would no longer point to the same person. An email is also easy to guess, which makes misuse easier.

Pass the identifier together with the connection name. When you pass connected_account_id instead, Scalekit ignores the identifier.

Set the mode in AgentKit > Settings > User Verification. New environments start with None.

Mode	What happens	Use it for
Custom user verifier	Scalekit redirects the user to your verify URL. Your server confirms the user and calls the verify API.	Production (recommended)
Scalekit users only	The person approving access must be signed in to your Scalekit dashboard.	Internal testing
None	Anyone with the link activates the account.	Development only

Verify users shows how to set up the custom user verifier.