Call Others' APIs on Users' Behalf

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. By the end of this quickstart, you should have an AI application integrated with Auth0 that can:

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

Pick your tech stack

LangGraph.js + Next.js
AI SDK + Next.js
LangGraph + FastAPI
AI SDK + React SPA

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.

Next steps

You have successfully added the ability to get access tokens for tool calling to your application. For next steps:

Call your APIs on user’s behalf docs.
Learn more about Client-initiated account linking.
Learn more about how Auth0’s Token Vault manages the tokens of supported identity providers.

Overview

Integrations

SDKs

Build with AI

Changelog

Call Others' APIs on Users' Behalf

Pick your tech stack

or Follow manual steps

Next steps

Overview

Integrations

SDKs

Build with AI

Changelog

​Pick your tech stack

​or Follow manual steps

​Next steps

Pick your tech stack

or Follow manual steps

Next steps