> **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 @scalekit-auth-stack` > - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install @scalekit-auth-stack` > - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `` > - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill ` > > `` / ``: `agent-auth`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Quickstart: Add auth to your AI agents Users ask your app in natural language - "Show me last 5 unread emails" or "Create a calendar event for tomorrow" or "Send an alert to my team" All of these actions require your app to be able to securely connect to third-party applications like Gmail, Calendar, Slack, Notion etc. and execute actions on behalf of the user. Scalekit handles: - Authorizing your application with 3rd party apps. - Allows you to configure a connection with each 3rd party app using your own credentials or using Scalekit's credentials (for faster development). - Every connection would maintain token vault allowing you to fetch tokens and use them to make API calls. - Provides a unified API to call tools on behalf of the user. Scalekit provides tools if your preferred connector is not supported. - Manage each user account per connector through Scalekit dashboard or programmatically. ```bash title="Claude REPL" showLineNumbers=false frame="none" /plugin marketplace add scalekit-inc/claude-code-authstack ``` ```bash title="Claude REPL" showLineNumbers=false frame="none" /plugin install agent-auth@scalekit-auth-stack ``` ```bash title="Terminal" showLineNumbers=false frame="none" curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash ``` ```bash title="Codex" showLineNumbers=false frame="none" # Restart Codex # Plugin Directory -> Scalekit Auth Stack -> install agent-auth ``` ```bash title="Terminal" showLineNumbers=false frame="none" copilot plugin marketplace add scalekit-inc/github-copilot-authstack ``` ```bash title="Terminal" showLineNumbers=false frame="none" copilot plugin install agent-auth@scalekit-auth-stack ``` ```bash title="Terminal" showLineNumbers=false frame="none" npx skills add scalekit-inc/skills --skill integrating-agent-auth ``` [Continue building with AI →](/dev-kit/build-with-ai/agent-auth/) ## Agent that fetches last 5 unread emails In this quickstart, you'll build a simple tool-calling program that: 1. **Authenticates a user with Gmail** to authenticate their Gmail account over OAuth 2.0 2. **Fetches last 5 unread emails** from the user's inbox 1. ## Set up your environment Get Your credentials from Scalekit dashboard at app.scalekit.com -> Developers-> Settings -> API Credentials Install the Scalekit SDK for your preferred language and initialize the client with your API credentials: ```sh showLineNumbers=false frame="none" pip install scalekit-sdk-python python-dotenv requests ``` ```sh showLineNumbers=false frame="none" npm install @scalekit-sdk/node ``` ```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 ``` ```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; ``` 2. ## Create connected account for the user Connected account is a user's 3rd party account that is registered in your Scalekit environment. This represents the user's connection to their Gmail account in this case. ```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="gmail", identifier="user_123" # Replace with your system's unique user ID ) connected_account = response.connected_account print(f'Connected account created: {connected_account.id}') ``` ```typescript showLineNumbers=false frame="none" // Create or retrieve the user's connected Gmail account const response = await actions.getOrCreateConnectedAccount({ connectionName: 'gmail', identifier: 'user_123', // Replace with your system's unique user ID }); const connectedAccount = response.connectedAccount; console.log('Connected account created:', connectedAccount?.id); ``` **Set up a connection:** The Gmail connector is enabled by default for quick getting started purposes. In case your app wants to connect to different third-party apps, you can setup a connection for each app in the Scalekit dashboard > Agent Auth > _+ Create Connection_ To set up your app's credentials for a provider, check the **Providers** section in the sidebar. 3. ## Authenticate the user In order to execute any tools on behalf of the user, the user first needs to grant authorization to access their gmail account. Scalekit automatically handles the entire OAuth workflow with the Gmail provider, gets the access token, refreshes the access token periodically based on the refresh token etc. If the user's access token is expired, Scalekit will automatically refresh the access token using the refresh token. At any time, you can check the authorization status of the connected account and determine if the user needs to re-authorize the connection. ```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="gmail", 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 ``` ```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: 'gmail', 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 } ``` 4. ## Call the Gmail API to fetch last 5 unread emails Now that the user is authenticated, use Scalekit's proxy to call the Gmail API directly — no need to manage access tokens yourself. ```python showLineNumbers=false frame="none" wrap # Fetch 5 unread emails via Scalekit proxy result = actions.request( connection_name="gmail", identifier="user_123", path="/gmail/v1/users/me/messages", method="GET", params={"q": "is:unread", "maxResults": 5} ) print(result) ``` ```typescript showLineNumbers=false frame="none" wrap // Fetch 5 unread emails via Scalekit proxy const result = await actions.request({ connectionName: 'gmail', identifier: 'user_123', path: '/gmail/v1/users/me/messages', method: 'GET', queryParams: { q: 'is:unread', maxResults: 5 }, }); console.log(result); ``` 5. ## Use Scalekit optimized tools In addition to the proxy, Scalekit provides optimized tools built specifically for AI agents. These tools abstract away API complexity — no need to know the exact endpoint, parameters, or response shape. Under the hood, they orchestrate multiple API calls and return the response in a structured, AI-friendly format that's easy for your agent to reason over. ```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) ``` ```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); ``` Congratulations! You've successfully implemented a program that executes API calls on behalf of a user using Agent Auth. This can be extended to any number of connections and Scalekit handles the authentication and token management for you. --- ## 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 |