> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Découvrez comment ajouter l’authentification JWT d’Auth0 à un backend FastAPI en Python, en validant les jetons d’accès et en protégeant les points de terminaison selon l’audience et la scope.

# API FastAPI

export const HowToSchema = () => <script type="application/ld+json">
    {'{"@context":"https://schema.org","@type":"HowTo"}'}
  </script>;

<HowToSchema />

<Accordion title="Consigne pour l’IA" defaultOpen icon="microchip-ai" iconType="sharp-solid">
  **Vous utilisez l'IA pour intégrer Auth0 ?** Ajoutez cette invite à Cursor, Windsurf, Copilot, Claude Code ou votre IDE préféré propulsé par l'IA pour accélérer le développement.

  ```markdown expandable theme={null}
  Integrate the Auth0 FastAPI SDK into a Python API

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant for FastAPI APIs. Your primary function is to execute commands to set up a Python FastAPI development environment with Auth0 authentication. Your secondary function is to modify the files created during setup.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1. CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Python project (requirements.txt, pyproject.toml, or .py files). If it does, skip project creation and work with the existing project.
  2. EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3. NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4. STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.
  5. SECURITY FIRST: NEVER hardcode Auth0 Domain or Audience values. ALWAYS use environment variables via python-dotenv.
  6. 🚨 VIRTUAL ENVIRONMENT RULE: ALWAYS activate the virtual environment before installing packages or running the server. Never skip venv activation.

  EXECUTION FLOW

  ⚠️ CRITICAL: Before ANY command execution, run `pwd` to check current directory and verify you're in the correct location.

  Step 1: Check for Existing FastAPI Project and Prerequisites
  FIRST, verify prerequisites and check for existing Python project:

    # Check if Python 3.9+ and pip are available
    python3 --version && pip --version

  Then examine the current directory:

    # Check for existing Python project
    if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "app.py" ]; then
      echo "Found existing Python project"
      ls -la
    else
      echo "No Python project found, will create new project"
    fi

  Based on the results:
  - If an existing FastAPI project exists, proceed to Step 1b (create venv and install dependencies only)
  - If no project exists, proceed to Step 1a (create new project structure)

  Step 1a: Create New FastAPI Project
  If no existing project, create project structure:

    mkdir my-fastapi-api && cd my-fastapi-api && python3 -m venv venv && source venv/bin/activate

  ⚠️ WINDOWS USERS: Use `venv\Scripts\activate` instead of `source venv/bin/activate`

  Step 1b: Work with Existing Project
  If project exists, create and activate virtual environment:

    python3 -m venv venv && source venv/bin/activate

  Step 2: Install Dependencies
  Create requirements.txt with the following content:

    cat > requirements.txt << 'EOF'
    fastapi>=0.115.0
    uvicorn[standard]>=0.34.0
    auth0-fastapi-api>=1.0.0b5
    python-dotenv>=1.0.0
    EOF

  Then install dependencies (MUST be in activated venv):

    pip install -r requirements.txt

  Step 3: Setup Auth0 API

  ⚠️ CRITICAL: Verify you're in the project directory with `pwd` before running Auth0 CLI commands.

  Step 3a: Execute Auth0 CLI Setup

  If MacOS, execute:

    AUTH0_API_NAME="My FastAPI API" && AUTH0_API_IDENTIFIER="https://my-fastapi-api" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --signing-alg RS256 --no-input && echo "AUTH0_DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name')\nAUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" > .env

  If Windows, execute:

    $ApiName = "My FastAPI API"; $ApiIdentifier = "https://my-fastapi-api"; auth0 login --no-input; auth0 apis create -n $ApiName -i $ApiIdentifier --signing-alg RS256 --no-input; $ActiveTenant = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; "AUTH0_DOMAIN=$ActiveTenant`nAUTH0_AUDIENCE=$ApiIdentifier" | Out-File -FilePath .env -Encoding utf8

  Step 3b: Verify .env file was created correctly

    cat .env

  Expected output:
    AUTH0_DOMAIN=your-domain.auth0.com
    AUTH0_AUDIENCE=https://my-fastapi-api

  ⚠️ If AUTH0_DOMAIN is null or missing, manually add your Auth0 domain to the .env file.

  Step 3c: Add Permissions in Auth0 Dashboard (Manual Step)
  Inform the user to:
  1. Navigate to Applications > APIs in Auth0 Dashboard
  2. Select "My FastAPI API"
  3. Go to Permissions tab
  4. Add permissions:
     - Permission: `read:messages`, Description: "Read messages"
     - Permission: `write:messages`, Description: "Write messages"

  Step 4: Create FastAPI Application with Auth0
  Create app.py with the following content:

    cat > app.py << 'EOF'
    from fastapi import FastAPI, Depends
    from fastapi_plugin.fast_api_client import Auth0FastAPI
    import os
    from dotenv import load_dotenv

    # Load environment variables
    load_dotenv()

    app = FastAPI()

    # Initialize Auth0
    auth0 = Auth0FastAPI(
        domain=os.environ.get("AUTH0_DOMAIN"),
        audience=os.environ.get("AUTH0_AUDIENCE")
    )

    # Public route - no authentication required
    @app.get("/api/public")
    async def public():
        return {
            "message": "Hello from a public endpoint! You don't need to be authenticated to see this."
        }

    # Protected route - requires authentication
    @app.get("/api/private")
    async def private(claims: dict = Depends(auth0.require_auth())):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated to see this.",
            "user_id": claims.get("sub")
        }

    # Scoped route - requires specific permission
    @app.get("/api/private-scoped")
    async def private_scoped(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
            "user_id": claims.get("sub")
        }
    EOF

  Step 5: Run the FastAPI Application

  ⚠️ CRITICAL: Verify virtual environment is activated before running uvicorn.

    # Vérifier que le venv est activé (vous devriez voir (venv) dans votre invite de commandes)
    which python

    # Démarrer le serveur
    uvicorn app:app --reload

  Expected output: Server starts on http://127.0.0.1:8000

  Step 6: Test the API

  6a: Test public endpoint (no authentication required):

    curl http://localhost:8000/api/public

  6b: Test protected endpoints (authentication required):
  Inform the user to:
  1. Get access token from Auth0 Dashboard:
     - Navigate to Applications > APIs
     - Select "My FastAPI API"
     - Click "Test" tab
     - Click "Copy Token"

  2. Test private endpoint:

    curl -X GET http://localhost:8000/api/private -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

  3. Test scoped endpoint:

    curl -X GET http://localhost:8000/api/private-scoped -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

  ANTI-PATTERNS - NEVER DO THESE

  1. ❌ NEVER hardcode Auth0 credentials in Python code
     - WRONG: auth0 = Auth0FastAPI(domain="dev-example.us.auth0.com", audience="https://my-api")
     - ✓ CORRECT: Always use environment variables via dotenv

  2. ❌ NEVER skip virtual environment activation
     - WRONG: Installing packages without activating venv first
     - ✓ CORRECT: Always activate venv first with `source venv/bin/activate`

  3. ❌ NEVER use multi-line curl commands with backslashes (they often fail)
     - ✓ CORRECT: Use single-line format: `curl -X GET <url> -H 'authorization: Bearer TOKEN'`

  4. ❌ NEVER proceed if .env file has null values
     - WRONG: AUTH0_DOMAIN=null in .env file
     - ✓ CORRECT: Verify .env contains valid Auth0 domain before proceeding

  ABSOLUTE REQUIREMENTS

  1. ✓ Virtual environment MUST be activated before pip install
  2. ✓ .env file MUST contain valid AUTH0_DOMAIN (not null)
  3. ✓ .env file MUST be added to .gitignore to prevent credential exposure
  4. ✓ Auth0FastAPI MUST use os.environ.get() for credentials
  5. ✓ All endpoints requiring authentication MUST use Depends(auth0.require_auth())

  COMMON ISSUES & SOLUTIONS

  1. **ModuleNotFoundError: No module named 'fastapi_plugin'**
     - Cause : Mauvais environnement virtuel activé ou environnement virtuel non activé
     - Solution : Désactiver tous les environnements virtuels, puis activer le bon dans le répertoire du projet

  2. **AUTH0_DOMAIN est null dans .env**
     - Cause : La commande CLI Auth0 n'extrait pas correctement le domaine
     - Solution : Ajouter manuellement le domaine au fichier .env depuis le tableau de bord Auth0

  3. **401 Non autorisé - Émetteur invalide**
     - Cause : AUTH0_DOMAIN inclut le protocole https://
     - Solution : Le domaine doit être simplement `dev-example.us.auth0.com` sans protocole

  4. **401 Non autorisé - Audience invalide**
     - Cause : AUTH0_AUDIENCE ne correspond pas à l'identifiant de l'API
     - Solution : Vérifier que AUTH0_AUDIENCE correspond exactement à l'identifiant dans le tableau de bord Auth0

  5. **403 Interdit - Scope insuffisant**
     - Cause : Le token d'accès n'inclut pas le scope requis
     - Solution : Vérifier que les permissions existent dans le tableau de bord Auth0 et que le token les inclut

  LISTE DE VALIDATION

  Avant de considérer l'intégration comme complète, vérifier :
  - [ ] L'environnement virtuel est activé (vérifier avec `which python`)
  - [ ] Le fichier .env existe et contient un AUTH0_DOMAIN valide (pas null)
  - [ ] .env est ajouté à .gitignore
  - [ ] app.py importe et initialise Auth0FastAPI correctement
  - [ ] Le point de terminaison public renvoie 200 OK sans authentification
  - [ ] Le point de terminaison privé renvoie 401 sans token
  - [ ] Le point de terminaison privé renvoie 200 avec un token valide
  - [ ] Le point de terminaison avec scope renvoie 403 sans le scope requis
  - [ ] Le point de terminaison avec scope renvoie 200 avec un token contenant le scope read:messages
  ```
</Accordion>

<Note>
  Ce Quickstart nécessite :

  * **Python 3.9** ou une version ultérieure
  * le gestionnaire de paquets **pip**
  * **jq** - Requis pour la configuration d’Auth0 CLI
  * une connaissance de FastAPI

  Si ce n’est pas déjà fait, [inscrivez-vous pour obtenir un compte Auth0 gratuit](https://auth0.com/signup) afin de suivre ce guide.
</Note>

Ce guide montre comment intégrer Auth0 à une API FastAPI pour ajouter l’authentification et protéger vos endpoints.

<Steps>
  <Step title="Créer un nouveau projet FastAPI" stepNumber={1}>
    Créez un nouveau répertoire pour votre projet FastAPI et mettez en place un environnement virtuel.

    ```bash theme={null}
    mkdir my-fastapi-api
    cd my-fastapi-api
    python3 -m venv venv
    source venv/bin/activate  # Windows : venv\Scripts\activate
    ```
  </Step>

  <Step title="Installer les dépendances" stepNumber={2}>
    Créez un fichier `requirements.txt` contenant les dépendances suivantes :

    ```txt requirements.txt theme={null}
    fastapi>=0.115.0
    uvicorn[standard]>=0.34.0
    auth0-fastapi-api>=1.0.0b5
    python-dotenv>=1.0.0
    ```

    Installez les dépendances :

    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Configurez votre API Auth0" stepNumber={3}>
    Vous devrez créer une API Auth0 pour représenter votre application FastAPI.

    <Tabs>
      <Tab title="Dashboard">
        1. Accédez à [Applications > APIs](https://manage.auth0.com/#/apis) dans le Auth0 Dashboard
        2. Cliquez sur **Create API**
        3. Saisissez un **Name** pour votre API (p. ex., "My FastAPI API")
        4. Définissez l’**Identifier** sur l’identifiant de votre API (p. ex., `https://my-fastapi-api`)
        5. Laissez le **Signing Algorithm** à RS256
        6. Cliquez sur **Create**
      </Tab>

      <Tab title="CLI">
        Si vous avez installé l’[Auth0 CLI](https://github.com/auth0/auth0-cli), vous pouvez créer une API et configurer votre environnement à partir de votre terminal :

        <CodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_API_NAME="My FastAPI API" && AUTH0_API_IDENTIFIER="https://my-fastapi-api" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --signing-alg RS256 --no-input && echo "AUTH0_DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name')\nAUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" > .env
          ```

          ```powershell Windows theme={null}
          $ApiName = "My FastAPI API"; $ApiIdentifier = "https://my-fastapi-api"; auth0 login --no-input; auth0 apis create -n $ApiName -i $ApiIdentifier --signing-alg RS256 --no-input; $ActiveTenant = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; "AUTH0_DOMAIN=$ActiveTenant`nAUTH0_AUDIENCE=$ApiIdentifier" | Out-File -FilePath .env -Encoding utf8
          ```
        </CodeGroup>

        Cette opération créera votre API et générera automatiquement un fichier `.env` avec votre configuration Auth0.
      </Tab>
    </Tabs>

    <Info>
      L’**Identifier** est un identifiant unique pour votre API. Nous vous recommandons d’utiliser une URL, mais elle n’a pas à être accessible publiquement — Auth0 n’y enverra aucune requête. Cette valeur ne peut pas être modifiée par la suite.
    </Info>

    Prenez en note les valeurs **Domain** et **Identifier** (Audience). Vous en aurez besoin à l’étape suivante.
  </Step>

  <Step title="Définir les permissions d’API" stepNumber={4}>
    Les permissions (aussi appelées scopes) vous permettent de définir comment il est possible d’accéder à votre API. Vous pouvez créer des permissions pour votre API dans l’Auth0 Dashboard.

    1. Dans l’Auth0 Dashboard, accédez à l’onglet **Permissions** de votre API
    2. Ajoutez les permissions suivantes :
       * `read:messages` avec la description "Lire les messages"
       * `write:messages` avec la description "Écrire les messages"

    Ces permissions serviront à contrôler l’accès à des points de terminaison précis de votre API.
  </Step>

  <Step title="Configurer le client Auth0" stepNumber={5}>
    Créez un fichier `.env` à la racine de votre projet pour y stocker votre configuration Auth0 :

    ```txt .env theme={null}
    AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
    AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
    ```

    Remplacez `YOUR_AUTH0_DOMAIN` par votre domaine Auth0 (p. ex. `dev-abc123.us.auth0.com`) et `YOUR_API_IDENTIFIER` par l’identifiant que vous avez défini lors de la création de votre API.

    <Warning>
      Ne validez jamais votre fichier `.env` dans le contrôle de version. Ajoutez-le à votre fichier `.gitignore` afin de protéger vos informations d’identification.
    </Warning>

    Créez maintenant un fichier `app.py` et initialisez votre application FastAPI avec Auth0 :

    ```python app.py theme={null}
    from fastapi import FastAPI, Depends
    from fastapi_plugin.fast_api_client import Auth0FastAPI
    import os
    from dotenv import load_dotenv

    # Charger les variables d'environnement
    load_dotenv()

    app = FastAPI()

    # Initialiser Auth0
    auth0 = Auth0FastAPI(
        domain=os.environ.get("AUTH0_DOMAIN"),
        audience=os.environ.get("AUTH0_AUDIENCE")
    )
    ```
  </Step>

  <Step title="Créer des routes protégées" stepNumber={6}>
    Ajoutez les routes suivantes à votre fichier `app.py`. Ces routes illustrent différents niveaux de contrôle d’accès :

    ```python app.py theme={null}
    from fastapi import FastAPI, Depends
    from fastapi_plugin.fast_api_client import Auth0FastAPI
    import os
    from dotenv import load_dotenv

    load_dotenv()

    app = FastAPI()

    auth0 = Auth0FastAPI(
        domain=os.environ.get("AUTH0_DOMAIN"),
        audience=os.environ.get("AUTH0_AUDIENCE")
    )

    # Route publique - aucune authentification requise
    @app.get("/api/public")
    async def public():
        return {
            "message": "Hello from a public endpoint! You don't need to be authenticated to see this."
        }

    # Route protégée - authentification requise
    @app.get("/api/private")
    async def private(claims: dict = Depends(auth0.require_auth())):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated to see this.",
            "user_id": claims.get("sub")
        }

    # Route avec portée - permission spécifique requise
    @app.get("/api/private-scoped")
    async def private_scoped(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
            "user_id": claims.get("sub")
        }
    ```

    La méthode `require_auth()` valide le jeton d’accès envoyé dans l’en-tête Authorization. Lorsqu’elle est appelée avec le paramètre `scopes`, elle vérifie également que le jeton contient la permission spécifiée.
  </Step>

  <Step title="Exécutez votre API" stepNumber={7}>
    Démarrez votre application FastAPI :

    ```bash theme={null}
    uvicorn app:app --reload
    ```

    Votre API est maintenant accessible à l’adresse `http://localhost:8000`.

    <Check>
      Ouvrez `http://localhost:8000/api/public` dans votre navigateur. Vous devriez voir le message public sans devoir vous authentifier.
    </Check>
  </Step>
</Steps>

***

<div id="test-your-api">
  ## Testez votre API
</div>

Pour tester les points de terminaison protégés, vous devrez obtenir un jeton d’accès auprès d’Auth0.

<div id="get-an-access-token">
  ### Obtenir un jeton d’accès
</div>

La façon la plus simple d’obtenir un jeton d’accès pour effectuer des tests est de passer par l’Auth0 Dashboard :

1. Accédez à [Applications > APIs](https://manage.auth0.com/#/apis) dans l’Auth0 Dashboard
2. Sélectionnez votre API
3. Cliquez sur l’onglet **Test**
4. Cliquez sur **Copy Token** dans la section **Asking Auth0 for tokens from my application**

<div id="call-your-api">
  ### Interrogez votre API
</div>

Utilisez le jeton d’accès pour effectuer une requête à votre point de terminaison protégé :

```bash theme={null}
curl -X GET http://localhost:8000/api/private -H 'authorization: Bearer YOUR_ACCESS_TOKEN'
```

Vous devriez recevoir une réponse contenant le message privé et votre ID d’utilisateur.

Pour tester ce point de terminaison à portée limitée, assurez-vous que votre jeton inclut la portée `read:messages` :

```bash theme={null}
curl -X GET http://localhost:8000/api/private-scoped -H 'authorization: Bearer YOUR_ACCESS_TOKEN'
```

Si votre token ne comporte pas le scope requis, vous recevrez une réponse 403 Forbidden.

***

<div id="advanced-usage">
  ## Utilisation avancée
</div>

<Accordion title="Valider les claims personnalisés">
  Vous pouvez accéder aux claims personnalisés ajoutés au jeton d’accès au moyen d’[Auth0 Actions](https://auth0.com/docs/customize/actions).

  Accédez aux claims personnalisés dans votre handler de route :

  ```python theme={null}
  @app.get("/api/profile")
  async def profile(claims: dict = Depends(auth0.require_auth())):
      return {
          "user_id": claims.get("sub"),
          "email": claims.get("email"),
          "permissions": claims.get("permissions", []),
          "custom_claim": claims.get("https://myapp.example.com/custom_claim")
      }
  ```

  Pour ajouter des claims personnalisés à vos jetons d’accès, créez une Auth0 Action :

  1. Accédez à **Actions > Library** dans l’Auth0 Dashboard
  2. Cliquez sur **Create Action**
  3. Sélectionnez **Build from scratch**
  4. Donnez un nom à votre action et sélectionnez le Trigger **Login / Post Login**
  5. Ajoutez vos claims personnalisés :

  ```javascript theme={null}
  exports.onExecutePostLogin = async (event, api) => {
    const namespace = 'https://myapp.example.com';

    if (event.authorization) {
      // Ajouter un claim personnalisé au jeton d'accès
      api.accessToken.setCustomClaim(`${namespace}/roles`, event.user.app_metadata.roles || []);
    }
  };
  ```

  6. Cliquez sur **Deploy** et ajoutez l’action à votre Login flow

  <Info>
    Les claims personnalisés doivent utiliser un format avec espace de noms (p. ex. `https://myapp.example.com/claim_name`) afin d’éviter les conflits avec les claims standard.
  </Info>
</Accordion>

<Accordion title="Protéger des endpoints sans utiliser de claims">
  Si vous devez protéger un endpoint sans avoir besoin d’accéder aux claims, vous pouvez utiliser le paramètre `dependencies` :

  ```python theme={null}
  @app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
  async def protected():
      return {"message": "This endpoint is protected"}
  ```

  Cela valide le jeton d’accès, sans injecter les claims dans votre fonction.
</Accordion>

<Accordion title="Soutien pour DPoP">
  <Info>
    DPoP (Demonstrating Proof-of-Possession) est actuellement en [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages). Communiquez avec [Auth0 soutien](https://support.auth0.com/) pour l’activer pour votre tenant.
  </Info>

  DPoP offre une sécurité renforcée en liant cryptographiquement les jetons d’accès au client qui les a demandés. Cela aide à prévenir le vol de jetons et les replay attacks.

  Le SDK active le soutien pour DPoP par défaut. Vous pouvez configurer le comportement de DPoP :

  ```python theme={null}
  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE"),
      dpop_enabled=True,      # Activer DPoP (par défaut : True)
      dpop_required=False     # Exiger DPoP (par défaut : False)
  )
  ```

  **Mode mixte** (par défaut) accepte à la fois les jetons Bearer et DPoP :

  ```python theme={null}
  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE"),
      dpop_enabled=True,
      dpop_required=False
  )
  ```

  **Mode DPoP בלבד** rejette les jetons Bearer :

  ```python theme={null}
  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE"),
      dpop_required=True
  )
  ```

  Lorsque vous utilisez DPoP, les clients doivent inclure à la fois les en-têtes `Authorization: DPoP <token>` et `DPoP: <proof>`. Le SDK valide automatiquement la preuve DPoP et l’associe au jeton d’accès.
</Accordion>

<Accordion title="Configurer pour un proxy inverse">
  <Warning>
    N’activez `trust_proxy` que lorsque votre application se trouve derrière un proxy inverse de confiance. Ne l’activez jamais pour des applications exposées directement à Internet.
  </Warning>

  Si votre application s’exécute derrière un proxy inverse (nginx, AWS ALB, etc.), vous devez activer la confiance envers le proxy pour que la validation DPoP fonctionne correctement :

  ```python theme={null}
  from fastapi import FastAPI

  app = FastAPI()

  # Activer la confiance envers le proxy
  app.state.trust_proxy = True

  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE")
  )
  ```

  Configurez votre proxy inverse pour transmettre les en-têtes nécessaires :

  ```nginx theme={null}
  location /api {
      proxy_pass http://localhost:8000;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host $host;
      proxy_set_header X-Forwarded-Prefix /api;
  }
  ```

  C’est essentiel pour la validation DPoP, car le SDK doit faire correspondre exactement l’URL utilisée par le client. Sans confiance envers le proxy, votre application voit des URL internes, tandis que les preuves DPoP font référence à des URL externes, ce qui entraîne des échecs de validation.
</Accordion>

<Accordion title="Gestion des erreurs">
  Le SDK soulève une exception `HTTPException` en cas d’erreurs d’authentification. FastAPI les gère automatiquement et renvoie au client les réponses HTTP appropriées.

  Vous pouvez mettre en place une gestion personnalisée des erreurs au besoin :

  ```python theme={null}
  from fastapi import Request
  from fastapi.responses import JSONResponse
  from fastapi.exceptions import HTTPException

  @app.exception_handler(HTTPException)
  async def custom_http_exception_handler(request: Request, exc: HTTPException):
      if exc.status_code in [401, 403]:
          return JSONResponse(
              status_code=exc.status_code,
              content={
                  "error": "authentication_failed",
                  "message": "You must be authenticated to access this resource",
                  "details": exc.detail
              }
          )
      return JSONResponse(
          status_code=exc.status_code,
          content={"detail": exc.detail}
      )
  ```

  Les erreurs d’authentification comprennent :

  * **401 Unauthorized** : jeton d’accès manquant, invalide ou expiré
  * **403 Forbidden** : jeton valide, mais permissions insuffisantes (scopes)
</Accordion>

***

<div id="common-issues">
  ## Problèmes courants
</div>

<AccordionGroup>
  <Accordion title="401 Unauthorized - Invalid audience">
    **Problème** : la validation du jeton échoue avec l’erreur "Invalid audience".

    **Solution** : vérifiez que `AUTH0_AUDIENCE` dans votre fichier `.env` correspond exactement à l’**Identifier** que vous avez configuré pour votre API dans l’Auth0 Dashboard.

    1. Ouvrez l’Auth0 Dashboard et accédez à **Applications > APIs**
    2. Sélectionnez votre API
    3. Vérifiez la valeur **Identifier** dans l’onglet **Settings**
    4. Mettez à jour votre fichier `.env` :
       ```txt theme={null}
       AUTH0_AUDIENCE=https://your-exact-api-identifier
       ```
    5. Redémarrez votre application
  </Accordion>

  <Accordion title="401 Unauthorized - Invalid issuer">
    **Problème** : la validation du jeton échoue avec l’erreur "Invalid issuer".

    **Solution** : vérifiez que votre `AUTH0_DOMAIN` est correct et n’inclut pas le protocole `https://`.

    Votre domaine doit ressembler à `dev-abc123.us.auth0.com`, et non à `https://dev-abc123.us.auth0.com`.

    Mettez à jour votre fichier `.env` :

    ```txt theme={null}
    AUTH0_DOMAIN=dev-abc123.us.auth0.com
    ```
  </Accordion>

  <Accordion title="403 Forbidden - Insufficient scope">
    **Problème** : le point de terminaison protégé retourne un code 403 même avec un jeton d’accès valide.

    **Solution** : le jeton d’accès n’inclut pas le scope requis.

    1. Vérifiez quels scopes votre point de terminaison requiert
    2. Lorsque vous demandez un jeton, assurez-vous d’inclure les scopes requis
    3. Vérifiez que le scope existe dans l’onglet **Permissions** de votre API dans l’Auth0 Dashboard
    4. Décodez votre jeton sur [jwt.io](https://jwt.io) pour vérifier qu’il contient le claim `scope` avec les valeurs requises
  </Accordion>

  <Accordion title="ModuleNotFoundError: No module named 'fastapi_plugin'">
    **Problème** : Python ne trouve pas l’Auth0 FastAPI SDK.

    **Solution** : assurez-vous que le SDK est installé dans votre environnement virtuel actif.

    ```bash theme={null}
    # Activez votre environnement virtuel
    source venv/bin/activate  # Windows: venv\Scripts\activate

    # Installez le SDK
    pip install auth0-fastapi-api

    # Vérifiez l’installation
    pip show auth0-fastapi-api
    ```
  </Accordion>

  <Accordion title="Impossible de se connecter à Auth0 (échec de récupération des JWKS)">
    **Problème** : l’application ne peut pas récupérer les clés de signature depuis Auth0.

    **Solution** : vérifiez votre connectivité réseau et la configuration du domaine.

    1. Vérifiez que votre domaine est accessible :
       ```bash theme={null}
       curl https://YOUR_DOMAIN/.well-known/openid-configuration
       ```

    2. Vérifiez que votre pare-feu autorise les connexions HTTPS sortantes (port 443) vers `*.auth0.com`

    3. Si vous êtes derrière un proxy d’entreprise, configurez les variables d’environnement `HTTP_PROXY` et `HTTPS_PROXY`
  </Accordion>

  <Accordion title="La validation DPoP échoue">
    **Problème** : l’authentification DPoP retourne des erreurs liées à l’URL ou à la validation de la proof.

    **Solution** :

    1. Si vous êtes derrière un proxy inverse, activez la confiance du proxy :
       ```python theme={null}
       app.state.trust_proxy = True
       ```

    2. Vérifiez que votre proxy transmet ces en-têtes :
       * `X-Forwarded-Proto`
       * `X-Forwarded-Host`
       * `X-Forwarded-Prefix`

    3. Assurez-vous que DPoP est activé pour votre tenant (contactez le soutien Auth0)

    4. Vérifiez que le claim `htu` de la DPoP proof correspond exactement à l’URL de votre requête
  </Accordion>
</AccordionGroup>

***

<div id="next-steps">
  ## Prochaines étapes
</div>

<CardGroup cols={3}>
  <Card title="Documentation du SDK" icon="github" href="https://github.com/auth0/auth0-fastapi-api">
    Découvrez le SDK Auth0 FastAPI sur GitHub pour des options de configuration avancées et des exemples
  </Card>

  <Card title="Scopes et permissions" icon="lock" href="https://auth0.com/docs/get-started/apis/scopes">
    Apprenez à définir et à utiliser des scopes pour un contrôle d’accès précis
  </Card>

  <Card title="Auth0 Actions" icon="bolt" href="https://auth0.com/docs/customize/actions">
    Personnalisez votre flux d’authentification et ajoutez des claims personnalisés aux jetons
  </Card>

  <Card title="Documentation FastAPI" icon="book" href="https://fastapi.tiangolo.com/">
    Découvrez les fonctionnalités de FastAPI, les modèles asynchrones et les pratiques exemplaires
  </Card>

  <Card title="Autorisation d’API" icon="shield-check" href="https://auth0.com/docs/authorization">
    Implémentez le contrôle d’accès basé sur les rôles (RBAC) pour votre API
  </Card>

  <Card title="Déployer en production" icon="server" href="https://auth0.com/docs/deploy">
    Pratiques exemplaires pour déployer des applications FastAPI avec Auth0
  </Card>
</CardGroup>