carla_urrea

I've been working as a software engineer since 2014, particularly as a backend engineer and doing system design. I consider myself a language-agnostic developer but if I had to choose, I like to work with Ruby and Python.  

After realizing how fun it was to create content and share experiences with the developer community I made the switch to Developer Advocacy. I like to learn and work with new technologies. 

When I'm not coding or creating content you could probably find me going on a bike ride, hiking, or just hanging out with my dog, Dasha. 

Staff Developer Advocate

Carla Urrea Stabile

Master the OpenID Authorization API 1.0. This guide shows you how to build a decoupled authorization system using Python and FastAPI.

A Guide to OpenID AuthZEN's Authorization API 1.0


raphael-do-vale

Raphael has more than two decades of experience in developing enterprise systems including coding, project planning, architecture, and specification. His technology stack includes Java, Spring, Python, Relational Databases, JavaScript, DevOps, and Artificial Intelligence. He has a PhD and Master's degree in the Semantic Web, winning awards during his studies. He also worked with Description Logic, Prolog, RDF, and OWL tech.

Raphael do Vale

I stream, blog, and make youtube videos about tech stuff. I love coding, I love AI, and I love building stuff!

Juan Cruz Martinez

Understand the architectural patterns, testing strategies, and design principles required to turn a simple script into a scalable, production-ready FastAPI application.

FastAPI Best Practices

apollo (1)

I am a Software Engineer who has taught over 1,000 developers how to code.

I love learning about new technology and making things!

Software Engineer

Mark Halpin

Learn the basics of FastAPI, how to quickly set up a server and secure endpoints with Auth0.

FastAPI is a relatively new Python framework that enables you to create applications very quickly. This framework allows you to read API request data seamlessly with built-in modules and is a lightweight alternative to Flask.

In this article, we will go over the features of `FastAPI`, set up a basic API, protect an endpoint using Auth0, and you'll learn how simple it is to get started.

## Prerequisites

Before you start building with [FastAPI](https://fastapi.tiangolo.com/), you need to have Python `3.9.0` at least, and a <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">free Auth0 account; you can sign up here</a>.

For this article, we will use [uv](https://docs.astral.sh/uv/). This tool replaces several tools that are commonly used to manage Python projects, such as `pipenv` and `poetry`. Implemented in Rust, it is extremely fast. To install it, run the following command (check uv website for other installation methods):

```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
```

With uv, you do not need to download and install Python. It does everything for you. Follow the steps below:

```bash
   uv init fastapi-example
```
This will create the fastapi-example folder with the files needed for uv. Now access the created folder and run the command below:

```bash
   cd fastapi-example
   uv venv --python 3.12
```

This command will create a virtual environment with Python 3.12. If this Python version is not available on your machine, uv will download it for you.

This creates a virtual environment, and it separates the dependencies from the rest of your computer libraries. In other words, you don't pollute the global namespace with libraries and dependencies, which might impact other Python projects.

Now, you can install the packages you are going to use: `FastAPI`, [Auth0-FastAPI](https://pypi.org/project/auth0-fastapi/), Pydantic Settings, for loading configuration, and the Auth0 library to ease OAuth 2.0 connection between FastAPI and Auth0:

```bash
uv add fastapi[standard] pydantic-settings auth0-fastapi-api
```

## Get Started with FastAPI

Now that all the libraries are installed, you can create a `main.py` file inside the `application` folder; that's where your API code will live. The contents of the `main.py` will look like this:

```python
"""main.py
Python FastAPI Auth0 integration example
"""

from fastapi import FastAPI

# Creates app instance
app = FastAPI()

@app.get("/api/public")
def public():
   # No access token required to access this route

   result = {
       "status": "success",
       "msg": ("Hello from a public endpoint! You don't need to be "
               "authenticated to see this.")
   }
   return result
```

Let's break this down:

- To start, you are importing the `FastAPI` library;
- Then creating your app by instantiating a `FastAPI()` object;
- After that, you use `@app.get` to define a route that handles `GET` requests;
- Finally, you have the path operation function called `public()`, which is a function that will run each time that route is called and it returns a dictionary with the welcome message.

Now that you've got your first endpoint code, to get the server up and running, run the following command on the **root** directory of the project:

```bash
 uv run fastapi dev --entrypoint application.main:app
```

With your server is running, you can go either to http://127.0.0.1:8000/docs to see the automatically generated documentation for the first endpoint like shown in the image below:

<picture>
<img src="https://images.ctfassets.net/23aumh6u8s0i/3fE3ngkaleHJw78ZNzQway/24719642235593cbf2016b4b86f38c54/Screen_Shot_2021-10-04_at_09.55.16.png" alt="ALT" style="width:85%; margin: 1em auto; border: solid black 0px; border-radius: 0px;">
</picture>

Or you can make your first request in a new terminal window by using `cURL`. Keep in mind that if you are a Windows user on a older version of the operating system, you will have to [install curl](https://curl.se/dlwiz/?type=bin) before running the following command:

```bash
curl -X 'GET' \
  --url <http://127.0.0.1:8000/api/public>
```

And you should see a JSON as a result of the request you just did similar to this:

```json
{
 "status": "success",
 "msg": "Hello from a public endpoint! You don't need to be authenticated to see this."
}
```
For simplicity's sake, you are going to use the `cURL` for the rest of this post.

## Set Up an Auth0 API

Before you begin protecting endpoints in your API, you’ll need to create an API on the [Auth0 Dashboard](https://manage.auth0.com/#/apis). If you don’t have an Auth0 account, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one</a>. Then, go to the [APIs section](https://manage.auth0.com/#/apis) and click on *Create API*.

This will open a new window for configuring the API. Set the following fields in that window:

* **Name**, a friendly name or description for the API. Enter **Fast API Example** for this sample.
* **Identifier**, which is an identifier that the client application uses to request [access tokens](https://auth0.com/docs/secure/tokens/access-tokens) for the API. Enter the string `https://fastapiexample.com`. This identifier is also known as **audience**.
* **Signing Algorithm**, leave the default setting, `RS256`.

After entering those values, click the *Create* button.

## Settings and Environment Variables

Now that you created your Auth0 API, you need to get back to the code. To effectively protect our endpoints, we need to [verify that the token](https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens) available in the `Authorization` header is valid, corresponds to our application, and was signed by the right party.

To do that, you’ll need to give to your application some Auth0 configuration values. We’ll use [FastAPI settings](https://fastapi.tiangolo.com/advanced/settings/) to retrieve these values either from a `.env` file or from environment variables.

For our local purposes, let’s start by storing the configuration values on a `.env` file like the following. Remember to update the values accordingly and to place the `.env` file in the root folder of your project:

```shell
# .env

AUTH0_DOMAIN = your.domain.auth0.com
AUTH0_API_AUDIENCE = https://your.api.audience
```

This configuration is the first piece of the puzzle of checking for the Auth0 configuration settings in the token validation stage. Another good rule to follow is to never commit your configuration files with environment variables to source code. To prevent this from occurring, you should create a `.gitignore` file in the project's root and add the `.env` file as an entry:

```shell
# .gitignore
.env
```

Next, let’s create a module to retrieve the application settings. Start by creating a new file `application/config.py` with the following contents:

```python
from functools import lru_cache

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
   auth0_domain: str
   auth0_api_audience: str

   class Config:
       env_file = ".env"

@lru_cache()
def get_settings():
   return Settings()
```

The defined `Settings` class uses the `Pydantic` settings module to retrieve the application’s settings directly from either the `.env` file or from environment variables. It is important that the definition properties match the configs ignoring capitalization.

## Configure the Auth0 Library

Auth0 FastAPI API Library handles most of the authentication and authorization logic for you. In your `main.py` file, you will need to import the `Auth0FastAPI` class from the `auth0_fastapi_api` library and instantiate it with the settings you retrieved from the `config.py` file:

```python
from fastapi_plugin.fast_api_client import Auth0FastAPI
from application.config import get_settings

settings = get_settings()
auth0 = Auth0FastAPI(
   domain=settings.auth0_domain,
   audience=settings.auth0_api_audience
)
```

`Auth0FastAPI` will act as the bridge between your app and the Auth0 Management API. The class will interact with Auth0 to retrieve the public keys used to verify the signature of the access tokens. The keys will be cached, and all requests to protected endpoints must have a JSON Web Token (JWT) in the authorization header and this will be the [access token](https://auth0.com/docs/secure/tokens/access-tokens) for the API. The access token will be validated against the public keys retrieved from the Auth0 API.

## Protect Your Endpoints

The final puzzle piece is to make the  `GET /api/private` endpoint use the Auth0 FastAPI library.

Here's what your `main.py` file should look like with all the necessary changes:

```python
"""Python FastAPI Auth0 integration example
"""

from fastapi import FastAPI, Depends
from fastapi_plugin.fast_api_client import Auth0FastAPI
from application.config import get_settings

# Creates app instance
app = FastAPI()

settings = get_settings()
auth0 = Auth0FastAPI(
   domain=settings.auth0_domain,
   audience=settings.auth0_api_audience
)

@app.get("/api/public")
def public():
   """No access token required to access this route"""

   result = {
       "status": "success",
       "msg": ("Hello from a public endpoint! You don't need to be "
               "authenticated to see this.")
   }
   return result

@app.get("/api/private")
def private(claims: dict = Depends(auth0.require_auth())):
   # A valid access token is required to access this route
   return claims
```

With this update, you are properly setting up your protected endpoint and doing all the verification steps for the access tokens you need.

Even though you started your server with the _dev_ mode enabled, you need to make sure the configuration is loaded. It is a good time to stop the `fastapi` process and then restart the server. That will guarantee the proper functionality of your API with the configuration parameters from the `.env` file or environment variables.

Before you can make requests to the protected endpoint in the `FastAPI` server, you need the access token from Auth0. You can get it by copying it from the Auth0 dashboard, in the `Test` tab of your API.

You can also use a curl `POST` request to Auth0's `oauth/token` endpoint to get the access token, and you can copy this request from the **Test** tab of your API in the Auth0 dashboard. The curl request will look like this; remember to fill the values as necessary:

```bash
curl -X 'POST' \
--url 'https://<YOUR DOMAIN HERE>/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data 'client_id=<YOUR CLIENT ID HERE>' \
--data client_secret=<YOUR CLIENT SECRET HERE> \
--data audience=<YOUR AUDIENCE HERE>
```

In the command line, you should see a response containing your access token, like this one:

```json
{
   "access_token": "<YOUR_ACCESS_TOKEN>",
   "expires_in": 86400,
   "token_type": "Bearer"
}
```

Now you can use this access token to access the private endpoint:

```bash
curl -X 'GET' \
--url '<http://127.0.0.1:8000/api/private>' \
--header  'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
```

If the request succeeds, the server will send back the payload of the access token:

```json
{
   "iss": "https://<YOUR_DOMAIN>/",
   "sub": "iojadoijawdioWDasdijasoid@clients",
   "aud": "http://<YOUR_AUDIENCE>",
   "iat": 1691399881,
   "exp": 1691486281,
   "azp": "ADKASDawdopjaodjwopdAWDdsd",
   "gty": "client-credentials"
}
```

Keep in mind that if the validation fails, you should see the details of what went wrong.

And that’s it — you have finished protecting the private endpoint and testing its protection.

## Recap

You learned quite a few things in this blog post. To start, you learned the basics of `FastAPI` by implementing two endpoints — one public, one private. You saw how simple it is to make requests to both of these endpoints. You created a verification class and saw how PyJWT helps you validate an Auth0 access token, and you learned what JWKS is.

You went through the process of creating your API in the Auth0 dashboard. You also learned how to secure one of your endpoints by leveraging the dependency injection system FastAPI provides to help you implement integrations. And you did all of this very quickly.

In short, you’ve learned how easy it is to get up and running with `FastAPI`, as well as how to use Auth0 for protecting your endpoints.

[In this GitHub repo](https://github.com/auth0-blog/auth0-python-fastapi-sample), you’ll find the full code for the sample application you built today. If you have any questions, ask them in the community forum thread for this blog post.

Thanks for reading!

Build and Secure a FastAPI Server with Auth0

andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Build a secure Python AI Agent with Microsoft Agent Framework and FastAPI and learn to use Auth0 Token Vault to securely connect to the Gmail API.

MS Agent Framework and Python: Use the Auth0 Token Vault to Call Third-Party APIs

Learn how to use LangGraph to integrate with external APIs with tool calling in Python, FastAPI, and LangChain.

Secure Third-Party Tool Calling: A Guide to LangGraph Tool Calling and Secure AI Integration in Python

Learn how to build a secure tool-calling AI agent using LangChain, FastAPI, and Python. You’ll learn how to protect a FastAPI API with Auth0 and to implement agent frontend that uses LangChain tool calling to interact with it securely.

In this tutorial, you’ll learn how to integrate LangChain into your existing stack even if your endpoints require authenticated users with specific roles.

By the end of this post, you’ll have two running projects built with FastAPI: an API, protected with Auth0 as the application backend, and a small frontend, that will use LangChain for tool calling and will be used by users. The frontend will send user prompts to be processed by LangChain that in turn will invoke the protected API.

The code is available [in this repository](https://a0.to/zoo-ai) for you to follow along. The code already has most of the system implemented, with placeholder sections designed to guide you through implementing authentication via LangChain. The repository will have two branches to help your study: one to begin with and another with the end result, to compare to what you have done.

If you are getting started with tool calling, I recommend you read the blog post linked below  before continuing to better understand tool calling in AI agents and how security is currently handled.

<include src="LinkCard" link="https://auth0.com/blog/genai-tool-calling-intro" title="Tool Calling in AI Agents: Empowering Intelligent Automation Securely" description="Discover how AI agents are taking center stage by seamlessly integrating with multiple digital tools like Gmail, Calendar, Slack, and Google Drive to be more efficient. Learn why it is important to secure them and how to do it." img="https://images.ctfassets.net/23aumh6u8s0i/4LrNhImjPcdPVpmCIrhlG9/4efed8dfb26630e6cf48b4a478a1f550/genai-tool-calling-intro.png" />

## Zoo AI: Our Demo Application

For this tutorial, we created a system solely for demonstration purposes. Zoo AI is a fictional zoo management platform that helps staff manage daily operations and respond to various situations. The platform has four main roles: 

* Veterinarians - Handle animal health and medical care.
* Coordinators - Oversee operations and can trigger emergency protocols.
* Janitors -  Maintain cleanliness and hygiene.
* Zookeepers - Provide daily care and feed the animals.

Any staff member can interact with our AI to report when something is happening or when some staff may need to take actions. Also, anything that happens to the animals needs to be logged.

## Prerequisites

You will need the following tools and services to build this application:

* Python 3.11 or later
* [Poetry for dependency management.](https://python-poetry.org/) Check [how to install](https://python-poetry.org/docs/#installation).
* An Auth0 for AI Agents account. [Create one](https://a0.to/ai-content).
* An OpenAI account and API key. [Create one](https://platform.openai.com/) or use any [other LLM provider supported by LangChain](https://js.langchain.com/docs/integrations/llms/).
* [Our git repository](https://a0.to/zoo-ai), cloned 

## Zoo AI Technological Stack

The Zoo AI management platform consists of two projects: API and Agent. Both projects have a similar stack to make the platform as simple as possible for demonstration purposes.

Both projects will also use the same Poetry environment to simplify set up. Poetry is completely optional but makes dependency management easier. You can check [the Poetry website](https://python-poetry.org/) for more details.

#### API Project (auth0-zoo-ai/api) Stack

*   **FastAPI**: Web framework for building the REST API
*   **Auth0-fastapi-api**: Authentication and authorization backend with the [Auth0 FastAPI SDK](https://github.com/auth0/auth0-fastapi-api)
*   **TinyDB**: Local NoSQL database for persistence
*   **Pydantic**: For data validation and serialization

Once you setup Auth0 following the steps on this blog post the API will work without requiring updates to the code so you can focus on what really matters: the agent we are building.

#### Agent Project (auth0-zoo-ai/agent) Stack

*   **LangChain**: Framework for building the AI agent
*   **OpenAI**: Language model integration
*   **FastAPI**: Web framework for exposing agent endpoints
*   **Requests:** Library for HTTP requests
*   **Auth0-fastapi**: Authentication and authorization for Web Applications

This provides the base structure for the Agent and you are going to make some modifications to it in order to securely perform tool calls, continue reading to learn how.

## Getting Started

Clone [the repository](https://a0.to/zoo-ai) and install the dependencies. All dependencies needed are already 
set in `pyproject.toml`.

```bash
git clone https://github.com/auth0-samples/auth0-zoo-ai
cd auth0-zoo-ai
git switch step1-firstparty-toolcalling
poetry install
```

Using branch `step1-firstparty-toolcalling` you’ll have both projects configured with all dependencies. To test it, we need to set up authentication and a few environment variables.

## Setting Up Auth0 Authentication for the FastAPI API

Before moving forward, we need to set up a few things in the Auth0 for AI Agents account you created in the prerequisites section.

Note: Since Auth0 for AI Agents is in Developer Preview, you need to use [this link](https://a0.to/ai-content) and sign up for a new tenant as it will have enabled all the features you’ll need.

We need to create a new API. The Agent will use this API to obtain an access token to perform actions on behalf of the user. Go to the API section in **Applications** and click on **Create API**.

![API creation in the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/54zmd09YFHooDo4JsKc7A7/3d211e86b43af40c9abbd47a5ef8708e/Uploaded_from_2025-06_AI_Content_Doc)

We need to set the name and the identifier. The identifier is the audience of the token. We will use it to set the audience of the token in the Agent project. Although the identifier is similar to a URL, it doesn’t have to be. It is just a string that will be used to identify the API.

* Name: Zoo Management API
* Identifier: [https://zoo-management-api](https://zoo-management-api)

![API creation form filled](https://images.ctfassets.net/23aumh6u8s0i/6ulWc71y62kZOLYfVzCX7t/a6b16a55c964d20ad8eccd0c1df0d51d/Uploaded_from_2025-06_AI_Content_Doc)

After clicking Create you’ll be taken to the API page. Navigate to the Settings tab check **Allow Offline Access** so we can generate Refresh Tokens for this API.

![Allow Offline Access toggled ON](https://images.ctfassets.net/23aumh6u8s0i/22ZOSvZnWKYcY2T9uctL1l/583580d7179192c730bc0158644f0357/Uploaded_from_2025-06_AI_Content_Doc)

Now we have to set up roles and inject them into our application access token.

In the Auth0 Dashboard, go to the **User Management** section and click in **Roles**.

![Roles page on the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/4gNAovUJIyUjSKVGfIovaL/7037fd9f84d99ebd66a34cf0a77e00e0/Uploaded_from_2025-06_AI_Content_Doc)

Now, click on **Create Role** and set the name `COORDINATOR`.

![Role creation form](https://images.ctfassets.net/23aumh6u8s0i/3bHDEmwnuoiuPlrZcYVn8p/66098d134f34ad9096eb9c2474b7b581/Uploaded_from_2025-06_AI_Content_Doc)

Do the same for all remaining roles: janitor, veterinarian, zookeeper. Keep the same name for both as they will be identified by it.

![List of all created roles](https://images.ctfassets.net/23aumh6u8s0i/545npYHoaQPzrE2mhBcxlM/e74b44e85f756e52afa125bdbf094aa5/Uploaded_from_2025-06_AI_Content_Doc)

To finish, we need Auth0 to add the role as a custom claim in the ID and access tokens.

<include src="LinkCard" link="https//auth0.com/blog/adding-custom-claims-to-id-token-with-auth0-actions/" title="Adding Custom Claims to ID Tokens with Auth0 Actions" description="Learn how to create a new custom action that will add a custom claim to your Auth0-issued ID Token" img="https://images.ctfassets.net/23aumh6u8s0i/1hMPYApOKrcrGV6Koi2Ekt/041eb09b09ae149d3d497beae72ee221/Introducing_Auth0_Actions02A.png" /><br>

Go to **Actions > Library** section. In the **Create Action** button, select **Build from scratch**.

![Menu to create new Action](https://images.ctfassets.net/23aumh6u8s0i/1oRq3RuWvQPgyPjXOUElxC/9b8dfef26ba16edd3c21881d628417c5/Uploaded_from_2025-06_AI_Content_Doc)

Give the action a name (e.g. _Add user role_) and select the **Trigger Login / Post Login**

![Action creation form](https://images.ctfassets.net/23aumh6u8s0i/5Ner8Wa4sTU2Oet4Xwt3hK/b8dfe18ec1f6042250d7e4db26891e1d/Uploaded_from_2025-06_AI_Content_Doc)

You will be prompted to a code editor screen. Add the following code:

```javascript
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://zooai/roles';
  if (event.authorization) {    
    api.accessToken.setCustomClaim(namespace, event.authorization.roles);
    api.idToken.setCustomClaim(namespace, event.authorization.roles);
  }
};
```

Click on **Deploy** and the code will be ready to be used.

To actually use the Auth0 Action you just created, we need to set up a **Trigger** for it. Go to **Actions > Triggers** and click on the post-login trigger.

![Actions Triggers](https://images.ctfassets.net/23aumh6u8s0i/BzZLQtBwuXjHLDZpVL9MQ/fcaf0331537bb69ef09d4e7abc54f4f0/Uploaded_from_2025-06_AI_Content_Doc)

Now, just drag and drop the custom action **Add user role** to the authentication flow and hit **Apply**.

![Adding action to the flow](https://images.ctfassets.net/23aumh6u8s0i/2pdwtSApg2K0KbckaP7TPY/4d5adc372c5a7199890842f436ae65f7/Uploaded_from_2025-06_AI_Content_Doc)

The action code will then be executed every time a token is generated and will add the claim `https://zooai/roles` to the access and ID tokens. You should always use a namespace (e.g. `https://zooai/`) to avoid conflicts with other claims.

Auth0 is configured. Now we need to test our code before making changes to it.

## Setting up API Project

Create a `.env` file in the `api/` folder with the following content:

```bash
AUTH0_DOMAIN=YOUR_AUTH0_TENANT_DOMAIN
API_AUDIENCE=https://zoo-management-api
```

To get `AUTH0_DOMAIN` you can access any **Application**, access Settings menu and copy the **Domain** value.

![Application page in the Dashboard](https://images.ctfassets.net/23aumh6u8s0i/OnjeEV9YsTYyZ1b3GnQYb/f5c472e360adce8c0d9c1b177141f778/Uploaded_from_2025-06_AI_Content_Doc)

Now run the API by typing the following instructions at the terminal:

```bash
cd api
poetry run uvicorn main:app
```

## Setting up Agent Project

Create the `.env` file in the agent folder:

```bash
touch agent/.env
```

And add the following content to it:

```txt
# Auth0
AUTH0_DOMAIN="YOUR_AUTH0_DOMAIN"
AUTH0_CLIENT_ID="YOUR_AUTH0_CLIENT_ID"
AUTH0_CLIENT_SECRET="YOUR_AUTH0_CLIENT_SECRET"
APP_BASE_URL="http://localhost:3000"
APP_SECRET_KEY="use [openssl rand -hex 32] to generate a 32 bytes value"
# OpenAI
OPENAI_API_KEY="YOUR_OPEN_AI_KEY"
API_AUDIENCE="https://zoo-management-api"
API_BASE_URL="http://localhost:8000"
```

Now, run the Agent service. The API project should still be running as both will communicate with each other:

```bash
cd agent
poetry run uvicorn main:app --reload --port 3000
```

Before using the application, we need to create some users in Auth0, each one with the roles you need. Go to **User Management > Users** and create as many users as you want. In the user page, go to the **Roles** tab and assign the role you desired. The project only supports one single role per user:

![Role assignment](https://images.ctfassets.net/23aumh6u8s0i/4PTlzT0lHoGxNJ9DibluZ4/1377dff7c22c4415efdc04dc0d964fab/Uploaded_from_2025-06_AI_Content_Doc)

Now, go to the browser and open the URL [http://localhost:3000/](http://localhost:3000/). You should see the application running. On the first time, you will be redirected to the Auth0 login page. After login, you will be redirected to the application and you should see the notifications for the user role. Go play with it and see how it reacts to many different queries. However, the LLM will only be able to talk with you without any access to our API. For that, we need to implement tools.

## Implementing Secure LangChain Tool Calling in Python

In our agent project, we need to create the `zoo_tools.py` file. This file will have all the tools that will call our API. Most importantly, these tools will be able to get the access token of the current user and forward it to the API.

Put the following code inside this file:

```python
import logging
import os

import requests
from dotenv import load_dotenv
from langchain_core.runnables import RunnableConfig
from langchain_core.tools import tool
from pydantic import BaseModel, Field

load_dotenv()

logger = logging.getLogger(__name__)

API_BASE_URL = os.getenv("API_BASE_URL")


def _get_headers(config: RunnableConfig) -> dict:
	access_token = config.get("configurable", {}).get("api_access_token")
	return {"Authorization": f"Bearer {access_token}"}
```

The section above contains the imports and the environment variable we are going to use to set the API base URL. We also defined the `get_headers` function, which is responsible for retrieving the user access token and creating a header for the API. We are going to explain how this access token is passed later. Now, we must define the tools that translate the API endpoints into LangChain tools.

```python
@tool
def list_animals(event: str, config: RunnableConfig) -> list[dict]:
	"""Get the list of all animals and their IDs."""
	try:
    	    logger.info("list animals %s", event)
           response = requests.get(f"{API_BASE_URL}/animal",    headers=_get_headers(config))
    	    response.raise_for_status()
    	    return response.json()
	except Exception as e:
     	    logger.exception("error")
    	    raise e
```

The LangChain Tool is a decorator that indicates that this function can be used by GenAI. You should always add docstrings so the agent can understand what the function does, that’s how the LLM will pick between one tool or the other. 

```python
class UpdateAnimalStatusArgs(BaseModel):
	animal_id: str = Field(..., description="ID of the animal to update")
	event_description: str = Field(
    	..., description="Clear and concise description of the event"
	)


@tool(args_schema=UpdateAnimalStatusArgs)
def update_animal_status(
	animal_id: str, event_description: str, config: RunnableConfig
) -> str:
	"""Add an event to an animal."""
	logger.info("add animal event %s", event_description)
	response = requests.post(
    	f"{API_BASE_URL}/animal/{animal_id}/status",
    	headers=_get_headers(config),
    	json={"status": event_description},
	)
	response.raise_for_status()
	return "event added"


class NotifyStaffArgs(BaseModel):
	event: str = Field(..., description="Event to notify staff about")
	staff_role: str = Field(
    	...,
    	description="Role of the staff to notify. Can be COORDINATOR, VETERINARIAN, JANITOR or ZOOKEEPER",
	)


@tool(args_schema=NotifyStaffArgs)
def notify_staff(event: str, staff_role: str, config: RunnableConfig) -> str:
	"""Notify a staff group about an event at the zoo."""
	logger.info("notify staff %s", event)
	response = requests.post(
    	f"{API_BASE_URL}/staff/notification/{staff_role}",
    	headers=_get_headers(config),
    	json={"description": event},
	)
	response.raise_for_status()
	return "notification sent"
```

We need to define the arguments that will be passed to the `update_animal_status` tool. We use Pydantic to define the arguments and the tool decorator to indicate that this function can be used by the LLM. LangChain will automatically parse the arguments and pass them to the function and the configured GenAI will be able to understand each argument. The `notify_staff` tool is similar to the `update_animal_status` tool. Since we need the exact name values for the role, we instruct the LLM which values are allowed.

Now, let's take a look at the `agent.py` file. This file will have all configuration of our LangChain with features like memory and graph (from LangGraph) definition. We need to make two changes to it. 

First, we need to register our tools into the tools list. You can change the following code:

```python
tools = [
	## ADD YOUR TOOLS HERE
]
```

To this:

```python
from zoo_tools import list_animals, notify_staff, update_animal_status

tools = [
	list_animals,
	update_animal_status,
	notify_staff,
]
```

Moreover, we need to pass the access token to the Configuration used by LangChain to pass and receive context between the graph.

Change this:

```python
config = {
    	"configurable": {
        	"thread_id": user_id,
    	}
}
```

To this:

```python
config = {
    	"configurable": {
        	"thread_id": user_id,
"api_access_token": token,
    	}
}
```

The token variable is already passed as an argument to our function, you can check in `main.py` file how we obtain it using Auth0 libraries.

Now you can test the agent again by running the command below:

```bash
poetry run uvicorn main:app --reload --port 3000
```

Your application should be ready to be used. You can login with the user you created in Auth0 and you should see the notifications of the user role. Go play with it and see how it reacts to many different queries!

![Zoo AI notification page](https://images.ctfassets.net/23aumh6u8s0i/72zb9J8kaSLY7mJD0x0lGn/e3dfb70457480a2436c1479ab5c63f9b/Uploaded_from_2025-06_AI_Content_Doc)

Note: All the code is on branch `step2-firstparty-toolcalling` of our repository.

## Recap

In this blog post you learned how to create a FastAPI API with the use of Dependency Injection and [Role-Based Access Control (RBAC)](https://auth0.com/docs/manage-users/access-control/rbac) with OAuth and Auth0. To use this API, you learned how to set up and deploy a LangChain application integrated with OpenAI and Auth0. This application enabled the LLM to securely connect to your API with context.

If you are building with GenAI you should check out our brand new product [Auth0 for AI Agents](http://a0.to/ai-content), to enable AI agents to securely access tools, workflows, and data with fine-grained control and just a few lines of code.

You can take a look at [the code that was used in these demos on GitHub](https://a0.to/zoo-ai) to try it out for yourself and stay tuned because we will have more content on tool calling in Python in future blog posts.

Secure LangChain Tool Calling with Python, FastAPI, and Auth0 Authentication

Most applications start with a need for tenant-level permissions. How do you control what users can do within their own organization? Let's learn how to implement RBAC in a FastAPI Application and OpenFGA to manage multi-tenancy.

"fastapi"