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.

Build with a coding agent

Claude Code

/plugin marketplace add scalekit-inc/claude-code-authstack

/plugin install agent-auth@scalekit-auth-stack

GitHub Copilot CLI

copilot plugin marketplace add scalekit-inc/github-copilot-authstack

copilot plugin install agent-auth@scalekit-auth-stack

40+ agents

npx skills add scalekit-inc/skills --skill integrating-agent-auth

Continue building with AI →

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:

   Python

   pip install scalekit-sdk-python python-dotenv requests

   Node.js

   npm install @scalekit-sdk/node

   Python

   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

   Node.js

   import { ScalekitClient } from '@scalekit-sdk/node';
   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

   # 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}')

   Node.js

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

   # 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

   Node.js

   // Generate authorization link if user hasn't authorized or token is expired
   if (connectedAccount?.status !== '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

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

   Node.js

   // 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',
     params: { 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

   response = actions.execute_tool(
       tool_name="gmail_fetch_mails",
       identifier="user_123",
       tool_input={
           "query": "is:unread",
           "max_results": 5,
       },
   )
   print(response)

   Node.js

   const toolResponse = await actions.executeTool({
     toolName: 'gmail_fetch_mails',
     connectedAccountId: connectedAccount?.id,
     toolInput: {
       query: 'is:unread',
       max_results: 5,
     },
   });
   console.log('Recent emails:', toolResponse.result);

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.