explain this: !-- Building with AI coding agents? If you're using an A

explain this:  > **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**: `claude plugin marketplace add scalekit-inc/claude-code-authstack && claude 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/) --- # AgentKit: Connect my agent to apps Build a working agent that makes authenticated tool calls on behalf of users, using Gmail as the example connector. <img src={quickstartArchitecture.src} alt="Architecture diagram: an AI agent connects through Scalekit MCP Gateway with delegated auth, scoped permissions, and tool calls to SaaS apps such as Gmail, Slack, and Salesforce." width={quickstartArchitecture.width} height={quickstartArchitecture.height} loading="eager" decoding="async" /> By the end of this guide, you'll have a working agent that fetches a user's last 5 unread Gmail messages (authenticated with their real account). Scalekit manages the OAuth flow, token storage, and API proxy so you focus on agent logic. ## Before you start Complete these steps in the Scalekit dashboard before writing any code: 1. **Create a Scalekit account** at [app.scalekit.com](https://app.scalekit.com). 2. **Configure a Gmail connector** at Dashboard → **AgentKit** > **Connections** > **Create Connection** → select **Gmail**. Create the connection in the dashboard before running any code. Then copy the exact **Connection name** from that connection and use that value in your code. It must match the dashboard exactly, and it is not always the provider slug `gmail`. Gmail is enabled by default in new Scalekit environments. To connect to other services, create a connection for each app under **AgentKit** > **Connections** > **Create Connection**. 3. **Copy your API credentials** at Dashboard → **Developers → Settings → API Credentials**. Save these three values as environment variables: - `SCALEKIT_CLIENT_ID` - `SCALEKIT_CLIENT_SECRET` - `SCALEKIT_ENV_URL` - `GMAIL_CONNECTION_NAME` (copy the exact Connection name from **AgentKit** > **Connections**) ## Build your agent ### Using a coding agent Install the Scalekit Auth Stack for your coding agent, complete the browser authorization when prompted, then paste the implementation prompt. The agent scaffolds connected account setup, the OAuth flow, and tool execution. ```bash title="Terminal" frame="terminal" showLineNumbers=false claude plugin marketplace add scalekit-inc/claude-code-authstack && claude plugin install agent-auth@scalekit-auth-stack ``` Installing the plugin sets up Scalekit's MCP server and triggers an OAuth authorization flow in your browser. Complete the authorization before continuing. This gives Claude Code direct access to your Scalekit environment to search docs, manage connections, and check connected account status. Then paste the prompt below. ### Codex ```bash title="Terminal" frame="terminal" showLineNumbers=false curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash ``` Restart Codex → Plugin Directory → **Scalekit Auth Stack** → install **agent-auth**. If a browser authorization prompt appears, complete the OAuth flow before continuing. Then paste the prompt below. ### GitHub Copilot CLI ```bash title="Terminal" frame="terminal" showLineNumbers=false copilot plugin marketplace add scalekit-inc/github-copilot-authstack copilot plugin install agent-auth@scalekit-auth-stack ``` If a browser authorization prompt appears, complete the OAuth flow before continuing. Then run: ```bash title="Terminal" frame="terminal" showLineNumbers=false wrap copilot "Configure Scalekit agent authentication for Gmail. Provide code to create a connected account, generate an authorization link, and fetch the last 5 unread emails using Scalekit's tool API." ``` ### Cursor > note: Marketplace under review > > Scalekit Auth Stack is under review on Cursor Marketplace. Use the local installer below until it's live. ```bash title="Terminal" frame="terminal" showLineNumbers=false curl -fsSL https://raw.githubusercontent.com/scalekit-inc/cursor-authstack/main/install.sh | bash ``` Reload Cursor → **Settings → Plugins** → enable **Agent Auth**. If a browser authorization prompt appears, complete the OAuth flow before continuing. Open chat (Cmd+L / Ctrl+L) and paste the prompt below. ### 40+ agents ```bash title="Terminal" frame="terminal" showLineNumbers=false npx skills add scalekit-inc/skills --skill integrating-agent-auth ``` Then ask your agent: "Configure Scalekit agent authentication for Gmail, create a connected account, generate an authorization link, and fetch the last 5 unread emails using Scalekit's tool API." ```md title="Implementation prompt" wrap showLineNumbers=false Configure Scalekit agent authentication for Gmail. Provide code to create a connected account, generate an authorization link, and, once the user authorizes, fetch the last 5 unread emails using Scalekit's tool API. ``` > caution: Review generated code before deploying > > Verify that token validation logic, error handling, and environment variable references match your application's requirements. ### Step by step ### 1. Set up your environment Install the Scalekit SDK and initialize the client with your API credentials: ```sh showLineNumbers=false frame="none" pip install scalekit-sdk-python python-dotenv requests ``` ### Node.js ```sh showLineNumbers=false frame="none" npm install @scalekit-sdk/node ``` ### Python ```python showLineNumbers=false frame="none" wrap import scalekit.client import os import requests from dotenv import load_dotenv load_dotenv() scalekit_client = scalekit.client.ScalekitClient( client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), env_url=os.getenv("SCALEKIT_ENV_URL"), ) actions = scalekit_client.actions connection_name = os.getenv("GMAIL_CONNECTION_NAME") # must match the Connection name in the dashboard exactly ``` ### Node.js ```typescript showLineNumbers=false frame="none" import { ScalekitClient } from '@scalekit-sdk/node'; import { ConnectorStatus } from '@scalekit-sdk/node/lib/pkg/grpc/scalekit/v1/connected_accounts/connected_accounts_pb'; import 'dotenv/config'; const scalekit = new ScalekitClient( process.env.SCALEKIT_ENV_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET ); const actions = scalekit.actions; const connectionName = process.env.GMAIL_CONNECTION_NAME!; // must match the Connection name in the dashboard exactly ``` ### 2. Create a connected account Scalekit tracks each user's third-party connection as a connected account. This is the record that holds their OAuth tokens. Creating it tells Scalekit to start managing the user's Gmail access on your behalf. This step fails if the Gmail connection has not been created in **AgentKit** > **Connections** yet, or if `connection_name` / `connectionName` does not match the dashboard exactly. ### Python ```python wrap {2} showLineNumbers=false frame="none" # Create or retrieve the user's connected Gmail account response = actions.get_or_create_connected_account( connection_name=connection_name, identifier="user_123" # Replace with your system's unique user ID ) connected_account = response.connected_account print(f'Connected account created: {connected_account.id}') ``` ### Node.js ```typescript showLineNumbers=false frame="none" // Create or retrieve the user's connected Gmail account const response = await actions.getOrCreateConnectedAccount({ connectionName, identifier: 'user_123', // Replace with your system's unique user ID }); const connectedAccount = response.connectedAccount; console.log('Connected account created:', connectedAccount?.id); ``` ### 3. Authenticate the user Your agent can't act on behalf of a user until they authorize access. Generate an authorization link, send it to the user, and Scalekit handles the rest: token exchange, storage, and automatic refresh. Once they complete the flow, the connected account status becomes `ACTIVE`. ### Python ```python showLineNumbers=false frame="none" wrap # Generate authorization link if user hasn't authorized or token is expired if(connected_account.status != "ACTIVE"): print(f"Gmail is not connected: {connected_account.status}") link_response = actions.get_authorization_link( connection_name=connection_name, identifier="user_123" ) print(f"🔗 click on the link to authorize Gmail", link_response.link) input(f"⎆ Press Enter after authorizing Gmail...") # In production, redirect user to this URL to complete OAuth flow ``` ### Node.js ```typescript showLineNumbers=false frame="none" wrap // Generate authorization link if user hasn't authorized or token is expired if (connectedAccount?.status !== ConnectorStatus.ACTIVE) { console.log('gmail is not connected:', connectedAccount?.status); const linkResponse = await actions.getAuthorizationLink({ connectionName, identifier: 'user_123', }); console.log('🔗 click on the link to authorize gmail', linkResponse.link); // In production, redirect user to this URL to complete OAuth flow } ``` Open the link in a browser and authorize the Gmail connection. Once complete, the connected account status updates to `ACTIVE` and your agent can act on the user's behalf. ### 4. Fetch emails via tool call Pass the tool name and your inputs to Scalekit. It handles the request to Gmail and returns a structured response your agent can reason over directly: no endpoint URLs, auth headers, or response parsing required. ### Python ```python showLineNumbers=false frame="none" wrap response = actions.execute_tool( tool_name="gmail_fetch_mails", identifier="user_123", tool_input={ "query": "is:unread", "max_results": 5, }, ) print(response) ``` ### Node.js ```typescript showLineNumbers=false frame="none" wrap const toolResponse = await actions.executeTool({ toolName: 'gmail_fetch_mails', connectedAccountId: connectedAccount?.id, toolInput: { query: 'is:unread', max_results: 5, }, }); console.log('Recent emails:', toolResponse.data); ``` ## Verify it works Run your agent and confirm: - The connected account status is `ACTIVE` after the user completes the Gmail OAuth flow. - The tool response contains structured email data (subject, sender, snippet, and timestamp) ready for your agent to process. If the connected account stays in a `non-ACTIVE` state, the user has not completed the OAuth flow. Regenerate the authorization link and try again. ## Next steps - [Secure user verification](/agentkit/user-verification/): Confirm the OAuth identity matches your logged-in user before activating a connected account. Required for production. - [Connected accounts](/agentkit/connected-accounts/): Manage user connections across multiple providers. - [Tool calling](/agentkit/tools/scalekit-optimized-tools/): Use Scalekit's optimized tools to call APIs without managing endpoints yourself. --- ## 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 |

This is documentation for Scalekit AgentKit - a platform that lets AI agents make authenticated API calls to third-party apps (like Gmail, Slack, Salesforce) on behalf of users.

Here's a breakdown of what it covers:

What is Scalekit AgentKit?

It's an auth infrastructure layer that sits between your AI agent and external SaaS apps. Instead of your agent managing OAuth flows, storing tokens, and calling APIs directly, Scalekit handles all of that. Your agent just calls Scalekit's "tool API" and gets back structured data.

The architecture looks like:

Your Agent → Scalekit MCP Gateway → Gmail / Slack / Salesforce
                    ↕
         (OAuth, token storage, API proxy)

The Four Core Concepts

1. Connections

A Connection is a configured integration to a specific app (e.g., Gmail). You set these up once in the Scalekit dashboard. Each connection has a unique name you reference in code.

2. Connected Accounts

A Connected Account is a per-user record that holds their OAuth tokens for a given connection. Think of it as: one Connection (Gmail app config) + many Connected Accounts (one per user who authorizes it).

3. Authorization Flow

Before your agent can act for a user, they must authorize access. Scalekit generates an OAuth URL, the user clicks it and grants permissions, and Scalekit stores the token. The connected account status then becomes ACTIVE.

4. Tool Execution

Once a user is authorized, your agent calls execute_tool() / executeTool() with a tool name (e.g., gmail_fetch_mails) and inputs. Scalekit handles the actual API call and returns structured data - no raw HTTP, no auth headers, no response parsing.

The Step-by-Step Flow (Gmail Example)

1. Dashboard: Create Gmail connection, copy credentials
2. Code: Initialize Scalekit client with env vars
3. Code: get_or_create_connected_account(user_id)  ← creates the per-user record
4. Code: If not ACTIVE → get_authorization_link() → send to user
5. User: Opens link, completes Google OAuth in browser
6. Code: execute_tool("gmail_fetch_mails", query="is:unread", max_results=5)
7. Agent: Receives structured email data (subject, sender, snippet, timestamp)

The AI Coding Agent Plugins (the comment at the top)

The HTML comment and blockquote at the very top is a meta-instruction for AI coding agents reading this documentation. It tells tools like Claude Code, GitHub Copilot, Codex, etc. to install a Scalekit plugin that gives them:

Full awareness of the Scalekit API schema
Pre-built "skills" so the agent generates correct Scalekit code instead of hallucinating API shapes

The available auth skill types are:

Skill	Purpose
`agentkit`	Agent-to-SaaS tool calling (this guide)
`full-stack-auth`	SSO/login for web apps
`mcp-auth`	Auth for MCP server integrations
`modular-sso`	Enterprise SSO (SAML/OIDC)
`modular-scim`	Directory sync / user provisioning

Key Takeaway

Scalekit AgentKit solves the hardest part of building agents that interact with real user accounts: delegated auth at scale. Without it, you'd need to implement OAuth for each provider, securely store and rotate tokens per user, and handle each app's API quirks yourself. Scalekit abstracts all of that into three method calls: create account, get auth link, execute tool.

This is a shared conversation. Sign in to Orris to start your own chat.