Calling first-party APIs

Learn how Auth0 for AI Agents enables AI agents to call first-party APIs on the user’s behalf.

Let your AI agent call your APIs on behalf of the authenticated user using access tokens securely issued by Auth0. Your API can be any API that you have configured in Auth0.

What you’ll learn

• Obtain an access token: learn how to authenticate and securely retrieve an access token from Auth0.
• Call an API: use the token to make a request to your API (e.g.: Auth0’s /userinfo endpoint).
• Present user data: pass the retrieved data back through an AI agent for consumption or display.

Before you start

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

1. Create an Auth0 Account

   To continue with this quickstart, you need to have an Auth0 account.
2. 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.
3. OpenAI Platform

   Set up an OpenAI account and API key.

Next.js

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/your-api/vercel-ai-next-js directory.

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

VS Code

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

1. Install dependencies

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

   • ai: Core AI SDK module that interacts with various AI model providers.
   • @ai-sdk/openai: OpenAI provider for the AI SDK.
   • @ai-sdk/react: React UI components for the AI SDK.
   • zod: TypeScript-first schema validation library.

   npm install ai@5.0.33 @ai-sdk/openai@2.0.24 @ai-sdk/react@2.0.33 zod@3.25.76
   

2. Update the environment file

   Copy the .env.example file to .env.local and update the variables with your Auth0 credentials. You can find your Auth0 domain, client ID, and client secret in the application you created in the Auth0 Dashboard.

3. Define a tool to call your API

   In this step, you’ll create a AI SDK tool to make the first-party API call. The tool fetches an access token to call the API.

   In this example, after taking in an Auth0 access token during user login, the tool returns the user profile of the currently logged-in user by calling the /userinfo endpoint.

   src/lib/tools/user-info.ts

   import { tool } from "ai";
   import { z } from "zod";
   
   import { auth0 } from "../auth0";
   
   export const getUserInfoTool = tool({
     description: "Get information about the current logged in user.",
     inputSchema: z.object({}),
     execute: async () => {
       const session = await auth0.getSession();
       if (!session) {
         return "There is no user logged in.";
       }
   
       const response = await fetch(
         `https://${process.env.AUTH0_DOMAIN}/userinfo`,
         {
           headers: {
             Authorization: `Bearer ${session.tokenSet.accessToken}`,
           },
         }
       );
   
       if (response.ok) {
         return { result: await response.json() };
       }
   
       return "I couldn't verify your identity";
     },
   });
   

4. Add the tool to the AI agent

   The AI agent processes and runs the user’s request through the AI pipeline, including the tool call. AI SDK simplifies this task with the streamText() method. Update the /src/app/api/chat/route.ts file with the following code:

   src/app/api/chat/route.ts

   //...
   import { getUserInfoTool } from "@/lib/tools/user-info";
   
   //... existing code
   
   export async function POST(req: NextRequest) {
     const { id, messages }: { id: string; messages: Array<UIMessage> } = await req.json();
   
     setAIContext({ threadID: id });
   
     const tools = {
       getUserInfoTool,
     };
   
     const stream = createUIMessageStream({
       originalMessages: messages,
       execute: async ({ writer }) => {
         const result = streamText({
           model: openai('gpt-4o-mini'),
           system: AGENT_SYSTEM_TEMPLATE,
           messages: convertToModelMessages(messages),
           stopWhen: stepCountIs(5),
           tools,
         });
   
         writer.merge(
           result.toUIMessageStream({
             sendReasoning: true,
           })
         );
       },
       onError: (err: any) => {
         console.log(err);
         return `An error occurred! ${err.message}`;
       },
     });
   
     return createUIMessageStreamResponse({ stream });
   }
   //... existing code
   

   You need an API Key from OpenAI or another provider to use an LLM. Add that API key to your .env.local file:

   .env.local

   # ...
   # You can use any provider of your choice supported by AI SDK
   OPENAI_API_KEY="YOUR_API_KEY"
   

   If you use another provider for your LLM, adjust the variable name in .env.local accordingly.

5. Test your application

   To test the application, run npm run dev and navigate to http://localhost:3000. To interact with the AI agent, you can ask questions like "who am I?" to trigger the tool call and test whether it successfully retrieves information about the logged-in user.

   User: who am I?
   AI: It seems that there is no user currently logged in. If you need assistance with anything else, feel free to ask!
   
   User: who am I?
   AI: You are Deepu Sasidharan. Here are your details: - .........
   

   That’s it! You’ve successfully integrated first-party tool-calling into your project.

   Explore the example app on GitHub.

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