Calling third-party APIs

Use Auth0 SDKs to fetch access tokens for social and enterprise identity providers from Auth0’s Token Vault. Using these access tokens, AI agents integrated with the application can call third-party APIs to perform tasks on the user’s behalf.

What you’ll learn

Retrieve access tokens for a Google social connection.
Integrate with an AI agent to call Google APIs.

Before you start

Before getting started, make sure you have completed the following steps:

Create an Auth0 Account

To continue with this quickstart, you need to have an Auth0 account.

Create an Auth0 Application

Go to your Auth0 Dashboard to create a new Auth0 Application.

Navigate to Applications > Applications in the left sidebar.
Click the Create Application button in the top right.
In the pop-up select Regular Web Applications and click Create.
Once the Application is created, switch to the Settings tab.
Scroll down to the Application URIs section.
Set Allowed Callback URLs as: http://localhost:3000/auth/callback
Set Allowed Logout URLs as: http://localhost:3000
Click Save in the bottom right to save your changes.

OpenAI Platform

Set up an OpenAI account and API key.

Next.js
FastAPI

Getting started using AI

To get started quickly:

Clone auth0-samples/auth0-ai-samples and navigate to auth0-ai-samples/call-apis-on-users-behalf/others-api/langchain-next-js directory.

Then, integrate Auth0 AI docs into your preferred AI tool:

VS Code
Cursor
Claude Code
Claude

Create a .vscode/mcp.json file and add:

{
  "servers": {
    "Auth0 for AI Agents": {
      "type": "http",
      "url": "https://auth0.com/ai/docs/mcp"
    }
  }
}

To learn more, read the VS Code documentation.

or Follow manual steps

Install packages

In the root directory of your project, install the following packages:

@auth0/ai-langchain: Auth0 AI SDK for LangChain built for AI agents powered by LangChain.
@langchain/langgraph: For building stateful, multi-actor applications with LLMs.
langchain: The LangChain library.
@langchain/core: LangChain core libraries.
@langchain/openai: OpenAI provider for LangChain.
@langchain/community: LangChain community integrations.
langgraph-nextjs-api-passthrough: API passthrough for LangGraph.

npm install @auth0/ai-langchain@3 @langchain/community@0.3 @langchain/core@0.3 @langchain/langgraph@0.3 @langchain/openai@0.6 langchain@0.3 langgraph-nextjs-api-passthrough@0.1

Update the environment file

Add to your environment file the following variables:

.env.local

# Auth0 configuration
APP_BASE_URL='http://localhost:3000'
AUTH0_SECRET='random 32 byte value'
AUTH0_DOMAIN='<your-auth0-domain>'
AUTH0_CLIENT_ID='<your-auth0-application-client-id>'
AUTH0_CLIENT_SECRET='<your-auth0-application-client-secret>'

# OpenAI API Key or any provider supported by the AI SDK
OPENAI_API_KEY="YOUR_API_KEY"

# LANGGRAPH
LANGGRAPH_API_URL=http://localhost:54367
LANGCHAIN_CALLBACKS_BACKGROUND=false

To get your Auth0 application’s AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET, navigate to the Settings tab in the Auth0 Dashboard. You’ll find these values in the Basic Information section at the top. Copy each value to the matching setting.Next, run this command to generate a random 32 byte value and copy it to the AUTH0_SECRET field:

generate random 32 byte value

openssl rand -hex 32

Lastly, set your OpenAI API key or use any provider supported by the AI SDK.

Set up Token Vault

Use the Auth0 AI SDK for LangChain to get an access token for the Google Social Connection using Token Vault:

connection: pass in the name of the connection you want to access.
scopes: pass in the scopes to be authorized for this connection.

Create a file src/lib/auth0-ai.ts to instantiate the Auth0 AI SDK client:

src/lib/auth0-ai.ts

import { Auth0AI, getAccessTokenForConnection } from "@auth0/ai-langchain";

// Get the access token for a connection via Auth0
export const getAccessToken = async () => getAccessTokenForConnection();

const auth0AI = new Auth0AI();

// Connection for Google services
export const withGoogleConnection = auth0AI.withTokenForConnection({
  connection: "google-oauth2",
  scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
});

Pass credentials to the tools

Create a file /src/lib/auth0.ts file with the following code:

src/lib/auth0.ts

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client();

// Get the refresh token from Auth0 session
export const getRefreshToken = async () => {
  const session = await auth0.getSession();
  return session?.tokenSet?.refreshToken;
};

Update your chat route, typically at /src/app/api/chat/[..._path]/route.ts to pass the refreshToken to your LangGraph agent to use the Auth0 AI SDK to get the Google access token from the server.

src/app/api/chat/[..._path]/route.ts

import { initApiPassthrough } from "langgraph-nextjs-api-passthrough";

import { getRefreshToken } from "@/lib/auth0";

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS, runtime } =
  initApiPassthrough({
    apiUrl: process.env.LANGGRAPH_API_URL,
    baseRoute: "chat/",
    bodyParameters: async (req, body) => {
      if (
        req.nextUrl.pathname.endsWith("/runs/stream") &&
        req.method === "POST"
      ) {
        return {
          ...body,
          config: {
            configurable: {
              _credentials: {
                refreshToken: await getRefreshToken(),
              },
            },
          },
        };
      }

      return body;
    },
  });

Calling APIs from a tool

Once the user is authenticated, you can fetch an access token from Token Vault using the Auth0 AI SDK. In this example, we fetch an access token for a Google social connection. Once you’ve obtained the access token for a connection, you can use it with an AI agent to fetch data during a tool call and provide contextual data in its response. This example uses GmailSearch from the @langchain/community tools. This tool will use the access token provided by Token Vault to query for emails.Update your tool call to request an access token, as shown in the following example:

src/lib/agent.ts

//...
import { GmailSearch } from "@langchain/community/tools/gmail";
import { getAccessToken, withGoogleConnection } from "./auth0-ai";

//... existing code

// Provide the access token to the Gmail tools
const gmailParams = {
  credentials: {
    accessToken: getAccessToken,
  },
};

const tools = [
  //... existing tools
  withGoogleConnection(new GmailSearch(gmailParams)),
];
//... existing code
export const agent = createReactAgent({
  llm,
  tools: new ToolNode(tools, {
    // Error handler must be disabled in order to trigger interruptions from within tools.
    handleToolErrors: false,
  }),
  // Modify the stock prompt in the prebuilt agent.
  prompt: AGENT_SYSTEM_TEMPLATE,
  store,
  checkpointer,
});

Add step-up authorization

When you try to use the tool, the application requests any additional Google scopes that are required but not yet authorized. This process is called step-up authorization.To implement, install the Auth0 AI Components for Next.js SDK to get the required UI components:

npx @auth0/ai-components add FederatedConnections

Add a new file, src/components/auth0-ai/FederatedConnections/FederatedConnectionInterruptHandler.tsx, with the following code:

src/components/auth0-ai/FederatedConnections/FederatedConnectionInterruptHandler.tsx

import { FederatedConnectionInterrupt } from "@auth0/ai/interrupts";
import type { Interrupt } from "@langchain/langgraph-sdk";

import { EnsureAPIAccess } from "@/components/auth0-ai/FederatedConnections";

interface FederatedConnectionInterruptHandlerProps {
  interrupt: Interrupt | undefined | null;
  onFinish: () => void;
}

export function FederatedConnectionInterruptHandler({
  interrupt,
  onFinish,
}: FederatedConnectionInterruptHandlerProps) {
  if (
    !interrupt ||
    !FederatedConnectionInterrupt.isInterrupt(interrupt.value)
  ) {
    return null;
  }

  return (
    <div key={interrupt.ns?.join("")} className="whitespace-pre-wrap">
      <EnsureAPIAccess
        mode="popup"
        interrupt={interrupt.value}
        onFinish={onFinish}
        connectWidget={{
          title: "Authorization Required.",
          description: interrupt.value.message,
          action: { label: "Authorize" },
        }}
      />
    </div>
  );
}

Now, update your chat window code to include the FederatedConnectionInterruptHandler component, for example:

src/components/chat-window.tsx

//...
import { FederatedConnectionInterruptHandler } from '@/components/auth0-ai/FederatedConnections/FederatedConnectionInterruptHandler';

//... existing code
export function ChatWindow(props: {
  //... existing code
}) {
  const [threadId, setThreadId] = useQueryState('threadId');
  const [input, setInput] = useState('');
  const chat = useStream({
    apiUrl: props.endpoint,
    assistantId: 'agent',
    threadId,
    onThreadId: setThreadId,
    onError: (e: any) => {
      console.error('Error: ', e);
      toast.error(`Error while processing your request`, { description: e.message });
    },
  });
  //... existing code
  return (
    <StickToBottom>
      <StickyToBottomContent
        className="absolute inset-0"
        contentClassName="py-8 px-2"
        content={
          chat.messages.length === 0 ? (
            <div>{props.emptyStateComponent}</div>
          ) : (
            <>
              <ChatMessages
                aiEmoji={props.emoji}
                messages={chat.messages}
                emptyStateComponent={props.emptyStateComponent}
              />
              <div className="flex flex-col max-w-[768px] mx-auto pb-12 w-full">
                <FederatedConnectionInterruptHandler interrupt={chat.interrupt} onFinish={() => chat.submit(null)} />
              </div>
            </>
          )
        }
        {/* ... existing code */}
      ></StickyToBottomContent>
    </StickToBottom>
  );
}

Now when step-up authorization is required, the user will see a prompt in the chat window asking them to authorize.

Test your application

Start your application. If you are already logged in, make sure to log out and log back in using Google. Then, ask your AI agent to fetch emails from your Gmail account!That’s it! You successfully integrated third-party API access using Token Vault into your app.

Continue Learning

Call Your APIs on User's Behalf

With Auth0, your AI apps can securely call your APIs on behalf of authenticated users.

Call Other's APIs on User's Behalf

Token Vault lets your AI agent call external APIs on a user’s behalf.

How-Tos

Check Google Calendar Availability

Use OpenAI, NextJS, and the Auth0-AI SDKs to check your Google Calendar availability.

List GitHub Repositories

Use OpenAI, NextJS, and the Auth0-AI SDKs to list your GitHub repositores

List Slack Channels

Use OpenAI, NextJS, and the Auth0-AI SDKs to list your Slack channels

Overview

Get Started

How-Tos

Calling third-party APIs

What you’ll learn

Getting started using AI

or Follow manual steps

Continue Learning

Call Your APIs on User's Behalf

Call Other's APIs on User's Behalf

How-Tos

Check Google Calendar Availability

List GitHub Repositories

List Slack Channels

Overview

Get Started

How-Tos

What you’ll learn

Getting started using AI

​or Follow manual steps

​Continue Learning

Call Your APIs on User's Behalf

Call Other's APIs on User's Behalf

​How-Tos

Check Google Calendar Availability

List GitHub Repositories

List Slack Channels

or Follow manual steps

Continue Learning

How-Tos