Skip to main content
Auth0 for AI Agents leverages Auth0 FGA to provide fine-grained authorization control for AI agents. As a result, when AI agents use Retrieval Augmented Generation (RAG) to provide sophisticated, relevant responses to user queries, they only have access to authorized data. By the end of this quickstart, you should have an AI application that can:
  1. Retrieve authorized data as context for a RAG pipeline.
  2. Use Auth0 FGA to determine if the user has authorization for the data.

​
Pick your tech stack

​
Prerequisites

Before getting started, make sure you:
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.
To learn more about Auth0 applications, read Applications.
3

Create an Auth0 FGA account

You need an Auth0 FGA account to complete this quickstart.
4

OpenAI Platform

Set up an OpenAI account and API key.

​
Download sample app

Start by downloading and extracting the sample app. Then open in your preferred IDE.

​
Install dependencies

In the root directory of your project, install the following dependencies:
  • @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: Core LangChain dependencies.
  • @langchain/openai: OpenAI provider for LangChain.
  • zod: TypeScript-first schema validation library.
  • langgraph-nextjs-api-passthrough: API passthrough for LangGraph.
npm install @auth0/ai-langchain@4 @langchain/[email protected] @langchain/[email protected] @langchain/[email protected] [email protected] [email protected]

​
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.

​
Set up an FGA Store

In the Auth0 FGA dashboard:
1
Navigate to Settings. In the Authorized Clients section, click + Create Client.
2
Give your client a name and mark all the client permissions that are required for your use case. For the quickstart, you’ll only need Read and query.
3
Click Create.
Set up FGA Store
Once your client is created, you’ll see a modal containing Store ID, Client ID, and Client Secret. Add or update an .env.local file with the following content to the root directory of the project. Click Continue to see the FGA_API_URL and FGA_API_AUDIENCE.The confirmation dialog will provide you with all the information that you need for your environment file.
.env.local
# You can use any provider of your choice supported by Vercel AI
OPENAI_API_KEY=<your-openai-api-key>

# Auth0 FGA
FGA_STORE_ID=<your-fga-store-id>
FGA_CLIENT_ID=<your-fga-store-client-id>
FGA_CLIENT_SECRET=<your-fga-store-client-secret>
FGA_API_URL=https://api.xxx.fga.dev
FGA_API_AUDIENCE=https://api.xxx.fga.dev/
Next, navigate to Model Explorer. You’ll need to update the model information with this:
model
  schema 1.1

type user

type doc
  relations
    define owner: [user]
    define viewer: [user, user:*]
Remember to click Save.

​
Secure the RAG Tool

After configuring your FGA Store, secure the RAG tool using Auth0 FGA and Auth0 AI SDK.The starter application is already configured to handle documents and embeddings.Document Upload and Storage
  • You can upload documents through the UI (src/app/documents/page.tsx).
  • Uploaded documents are processed by the API route (src/app/api/documents/upload/route.ts).
  • APIs for uploading and retrieving documents are defined in (src/lib/actions/documents.ts).
  • Database is defined in src/lib/db.
  • FGA helpers are defined in src/lib/fga.
  • Documents are stored as embeddings in a vector database for efficient retrieval (src/lib/rag/embedding.ts).
Access Control with Auth0 FGA
  • When a document is uploaded, the app automatically creates FGA tuples to define which users can access which documents. A tuple signifies a user’s relation to a given object. For example, the below tuple implies that all users can view the <document name> object.
  • Navigate to the Tuple Management section to see the tuples being added. If you want to add a tuple manually for a document, click + Add Tuple. Fill in the following information:
    • User: user:*
    • Object: select doc and add <document name> in the ID field
    • Relation: viewer

​
Create a RAG tool

Define a RAG tool that uses the FGAFilter to filter authorized data from the vector database:
src/lib/tools/context-docs.ts
import { tool } from "@langchain/core/tools";
import { z } from "zod";
import { FGARetriever } from "@auth0/ai-langchain/RAG";

import { getVectorStore } from "@/lib/rag/embedding";

export const getContextDocumentsTool = tool(
  async ({ question }, config) => {
    const user = config?.configurable?._credentials?.user;

    if (!user) {
      return "There is no user logged in.";
    }

    const vectorStore = await getVectorStore();

    if (!vectorStore) {
      return "There is no vector store.";
    }

    const retriever = FGARetriever.create({
      retriever: vectorStore.asRetriever(),
      buildQuery: (doc) => ({
        user: `user:${user?.email}`,
        object: `doc:${doc.metadata.documentId}`,
        relation: "can_view",
      }),
    });

    // filter docs based on FGA authorization
    const documents = await retriever.invoke(question);
    return documents.map((doc) => doc.pageContent).join("\n\n");
  },
  {
    name: "get_context_documents",
    description:
      "Use the tool when user asks for documents or projects or anything that is stored in the knowledge base.",
    schema: z.object({
      question: z.string().describe("the users question"),
    }),
  }
);

​
Use the RAG tool from AI agent

Call the tool from your AI agent to get data from documents. First, update the /src/app/api/chat/[..._path]/route.ts file with the following code to pass the user credentials to your agent:
src/app/api/chat/[..._path]/route.ts
import { initApiPassthrough } from "langgraph-nextjs-api-passthrough";

import { getUser, getAccessToken } 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: {
                user: await getUser(),
              },
            },
          },
        };
      }

      return body;
    },
    headers: async () => {
      const accessToken = await getAccessToken();
      return {
        Authorization: `Bearer ${accessToken}`,
      };
    },
  });
Next, add the following code to src/lib/auth0.ts:
src/lib/auth0.ts
import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  authorizationParameters: {
    // In v4, the AUTH0_SCOPE and AUTH0_AUDIENCE environment variables are no longer automatically picked up by the SDK.
    // Instead, we need to provide the values explicitly.
    scope: process.env.AUTH0_SCOPE,
    audience: process.env.AUTH0_AUDIENCE,
  },
});

// Get the Access token from Auth0 session
export const getAccessToken = async () => {
  const tokenResult = await auth0.getAccessToken();

  if(!tokenResult || !tokenResult.token) {
    throw new Error("No access token found in Auth0 session");
  }

  return tokenResult.token;
};

export const getUser = async () => {
  const session = await auth0.getSession();
  return session?.user;
};

​
Add Custom Authentication

For more information on how to add custom authentication for your LangGraph Platform application, read the Custom Auth guide.
In your langgraph.json, add the path to your auth file:
langgraph.json
{
  "node_version": "20",
  "graphs": {
    "agent": "./src/lib/agent.ts:agent"
  },
  "env": ".env",
  "auth": {
    "path": "./src/lib/auth.ts:authHandler"
  }
}
Then, in your auth.ts file, add your auth logic:
src/lib/auth.ts
import { createRemoteJWKSet, jwtVerify } from "jose";

const { Auth, HTTPException } = require("@langchain/langgraph-sdk/auth");

const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN;
const AUTH0_AUDIENCE = process.env.AUTH0_AUDIENCE;

// JWKS endpoint for Auth0
const JWKS = createRemoteJWKSet(
  new URL(`https://${AUTH0_DOMAIN}/.well-known/jwks.json`)
);

// Create the Auth instance
const auth = new Auth();
// Register the authentication handler
auth.authenticate(async (request: Request) => {
  const authHeader = request.headers.get("Authorization");
  const xApiKeyHeader = request.headers.get("x-api-key");
    /**
     * LangGraph Platform will convert the `Authorization` header from the client to an `x-api-key` header automatically
     * as of now: https://docs.langchain.com/langgraph-platform/custom-auth
     *
     * We can still leverage the `Authorization` header when served in other infrastructure w/ langgraph-cli
     * or when running locally.
     */
    // This header is required in Langgraph Cloud.
    if (!authHeader && !xApiKeyHeader) {
      throw new HTTPException(401, {
        message: "Invalid auth header provided.",
      });
    }

    // prefer the xApiKeyHeader first
    let token = xApiKeyHeader || authHeader;

    // Remove "Bearer " prefix if present
    if (token && token.startsWith("Bearer ")) {
      token = token.substring(7);
    }

    // Validate Auth0 Access Token using common JWKS endpoint
    if (!token) {
      throw new HTTPException(401, {
        message:
          "Authorization header format must be of the form: Bearer <token>",
      });
    }

    if (token) {
      try {
        // Verify the JWT using Auth0 JWKS
        const { payload } = await jwtVerify(token, JWKS, {
          issuer: `https://${AUTH0_DOMAIN}/`,
          audience: AUTH0_AUDIENCE,
        });

        console.log("✅ Auth0 JWT payload resolved!", payload);

        // Return the verified payload - this becomes available in graph nodes
        return {
          identity: payload.sub!,
          email: payload.email as string,
          permissions:
            typeof payload.scope === "string" ? payload.scope.split(" ") : [],
          auth_type: "auth0",
          // include the access token for use with Auth0 Token Vault exchanges by tools
          getRawAccessToken: () => token,
          // Add any other claims you need
          ...payload,
        };
      } catch (jwtError) {
        console.log(
          "Auth0 JWT validation failed:",
          jwtError instanceof Error ? jwtError.message : "Unknown error"
        );
        throw new HTTPException(401, {
          message: "Invalid Authorization token provided.",
        });
      }
    }
});

export { auth as authHandler };
Now, update the src/lib/agent.ts file with the following code to add the tool to your agent:
src/lib/agent.ts
import { getContextDocumentsTool } from "./tools/context-docs";

//... existing code

const tools = [
  //... existing tools
  getContextDocumentsTool,
];
//... existing code

​
Test your application

Start the database and create required tables:
# start the postgres database
docker compose up -d
# create the database schema
npm run db:migrate
Start the application with npm run all:dev. Then, navigate to http://localhost:3000.
This will open the LangGraph Studio in a new tab. You can close it as we won’t require it for testing the application.
Upload a document from the documents tab and ask your AI agent a question about the document. You should get a response with the relevant information.Go to an incognito window, log in as a different user, and ask it the same question. You should not get a response.Share the document from the documents page to the second user and try again. You should see the information now.That’s it! You successfully integrated RAG protected by Auth0 FGA into your project.Explore the example app on GitHub.

​
Next steps