Consommer les Events avec l’Events API

Récupérez les événements d’Auth0 selon votre propre calendrier à l’aide de l’Events API fondée sur les événements envoyés par le serveur (SSE).

L’Events API offre une solution de rechange à Event Streams fondée sur l’extraction. Au lieu qu’Auth0 envoie les événements vers une destination, votre application ouvre une connexion de longue durée à GET /api/v2/events et reçoit les événements sous forme de flux d’événements envoyés par le serveur (SSE). Vous contrôlez quand vous connecter, comment reprendre après une déconnexion et à quel rythme consommer les événements.

Cette approche est utile lorsque vous devez :

• Traiter les événements à votre propre rythme sans mettre en place un webhook endpoint.
• Rejouer les événements à partir d’un moment précis pour le remplissage rétroactif ou la récupération.
• Intégrer des systèmes qui privilégient l’interrogation périodique plutôt qu’une distribution par envoi.

​

Fonctionnement de l’Events API

Lorsque votre application se connecte à l’Events API, elle reçoit un flux de messages SSE. Chaque message comprend un champ id qui sert d’offset. Si la connexion est interrompue, votre application se reconnecte et fournit le dernier offset reçu. Auth0 reprend alors la transmission à partir de ce point, de sorte qu’aucun événement n’est perdu.

Le flux SSE comprend les types de messages suivants :

Type de message	Objectif
:connected	Confirme que la connexion est établie. Il s’agit d’un commentaire SSE, et non d’un événement de données.
retry: <ms>	Indique au client SSE combien de temps attendre avant de se reconnecter après une déconnexion.
event: <type> (par exemple, user.created)	Un véritable événement dont le payload complet se trouve dans le champ data.
event: offset-only	Un marqueur de progression envoyé à intervalles réguliers (selon la fréquence du heartbeat). Il met à jour l’offset sans transmettre de données d’événement.
: suivi de texte (par exemple, : heartbeat)	Un commentaire de maintien en vie qui empêche les proxys et les répartiteurs de charge de fermer les connexions inactives. Aucune action requise.
event: error	Une erreur terminale. Le flux se ferme après ce message.

​

Exemple de flux SSE

:connected

retry: 2000

event: user.created
id: MTIzNDIzNDEzCg==
data: {"offset":"MTIzNDIzNDEzCg==","event":{"id":"evt_abc123","type":"user.created","time":"2025-06-01T12:00:00Z","data":{"object":{"user_id":"auth0|123","email":"[e-mail]"}}}}

event: offset-only
id: 4LcuTXmVDASuNRQt
data: {"offset":"4LcuTXmVDASuNRQt"}

: heartbeat

event: user.updated
id: NTY3ODkwMTIzCg==
data: {"offset":"NTY3ODkwMTIzCg==","event":{"id":"evt_def456","type":"user.updated","time":"2025-06-01T12:05:00Z","data":{"object":{"user_id":"auth0|123","email":"[e-mail]"}}}}

​

Prérequis

Avant de commencer, assurez-vous d’avoir :

• Un tenant Auth0 avec Events activé. Le nombre de connexions Event Stream disponibles dépend de votre plan :

  Plan	Limite de connexions
  Free	1
  Self-service	4
  Enterprise	8

• Un jeton d’accès à l’API de gestion avec la portée read:events. Pour en savoir plus, consultez Jetons d’accès à l’API de gestion.

​

Se connecter à l’API Events

Ouvrez une connexion SSE au point de terminaison des événements de votre tenant. L’exemple suivant utilise curl :

curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    "https://YOUR_DOMAIN/api/v2/events"

​

Paramètres de requête

Utilisez les paramètres de requête pour filtrer le flux ou le reprendre :

Paramètre	Type	Description
from	string	Un offset renvoyé dans un champ id précédent. La transmission reprend après cet offset.
from_timestamp	string	Un horodatage ISO 8601. Renvoie les événements survenus à ce moment ou après. Ne peut pas être utilisé avec from. À privilégier pour la configuration initiale ou pour rejouer des événements à partir d’un moment précis; pour un traitement en continu, il vaut mieux reprendre avec from, puisque les offsets sont plus précis.
event_type	string	Le type d’événement à inclure. Répétez le paramètre pour chaque type (par exemple, event_type=user.created&event_type=user.updated).

curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    "https://YOUR_DOMAIN/api/v2/events?event_type=user.created&event_type=user.updated&from_timestamp=2025-06-01T00:00:00Z"

​

Reprendre après une déconnexion

Les connexions SSE peuvent être interrompues pour de nombreuses raisons : problèmes de réseau, expiration du token ou renouvellement périodique des connexions côté serveur (Auth0 ferme périodiquement les connexions pour la répartition de charge — généralement toutes les quelques minutes). Les bibliothèques clientes SSE standard gèrent cela de façon transparente en se reconnectant et en envoyant le dernier offset.

Il existe deux façons de fournir l’offset lors de la reconnexion :

• En-tête Last-Event-ID — le mécanisme standard de reconnexion SSE. La plupart des bibliothèques clientes SSE définissent automatiquement cet en-tête lors de la reconnexion.
• Paramètre de requête from — utilisez-le lorsque votre client ne prend pas en charge l’en-tête Last-Event-ID.

Si les deux sont fournis, l’en-tête Last-Event-ID est prioritaire.

curl -N --http2 \
    -H "Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN" \
    -H "Accept: text/event-stream" \
    -H "Last-Event-ID: MTIzNDIzNDEzCg==" \
    "https://YOUR_DOMAIN/api/v2/events"

Enregistrez la valeur id la plus récente de chaque message (y compris les messages offset-only) dans un stockage persistant. Si votre application redémarre, utilisez l’offset enregistré pour reprendre la livraison là où elle s’était arrêtée.

​

Gérer les types de messages

​

Événements réels

Les messages dont le champ event correspond à un type d’événement connu (par exemple, user.created) contiennent le payload complet de l’événement dans le champ data. Analysez le JSON et traitez l’événement selon votre logique d’affaires.

​

Messages offset-only

Auth0 envoie des messages offset-only à intervalles réguliers (à la fréquence du heartbeat) pour faire avancer votre position dans le stream. Ces messages ne contiennent pas de payload d’événement. Mettez à jour l’offset enregistré lorsque vous les recevez afin qu’une reconnexion ultérieure ne rejoue pas les événements que vous avez déjà dépassés.

​

Messages d’erreur

Un message event: error signale un problème fatal, comme un offset expiré ou un problème côté serveur. Après réception de ce message, le flux se ferme. Votre application devrait consigner l’erreur, puis se reconnecter en utilisant l’offset approprié ou un nouveau from_timestamp.

​

Signaux de vie

Les lignes commençant par : sont des commentaires SSE servant de signaux de vie. Elles permettent de maintenir la connexion active à travers les proxys et les répartiteurs de charge. Aucun traitement n’est requis.

​

Rotation des connexions côté serveur

Auth0 ferme périodiquement les connexions SSE pour répartir la charge (généralement toutes les quelques minutes). Il s’agit d’un comportement attendu, et non d’une erreur. Les bibliothèques clientes SSE standard (y compris le package npm eventsource) se reconnectent automatiquement à l’aide de l’en-tête Last-Event-ID, de sorte que votre application reprend à partir du bon offset sans perdre d’événements.

Si vous développez un client SSE personnalisé, assurez-vous qu’il gère correctement les interruptions de connexion en enregistrant le dernier offset et en se reconnectant avec celui-ci.

​

Mettre en place un consommateur

L’exemple Node.js suivant présente un consommateur minimal de l’Events API qui traite les événements et enregistre l’offset dans un fichier.

const EventSource = require("eventsource");
const fs = require("fs");

const OFFSET_FILE = "./offset.txt";
const AUTH0_DOMAIN = "YOUR_DOMAIN";
const TOKEN = "YOUR_MANAGEMENT_API_TOKEN";

function loadOffset() {
    try {
        return fs.readFileSync(OFFSET_FILE, "utf8").trim();
    } catch {
        return null;
    }
}

function saveOffset(offset) {
    fs.writeFileSync(OFFSET_FILE, offset);
}

function connect() {
    const offset = loadOffset();
    const params = new URLSearchParams();
    params.append("event_type", "user.created");
    params.append("event_type", "user.updated");
    params.append("event_type", "user.deleted");

    if (offset) {
        params.append("from", offset);
    }

    const url = `https://${AUTH0_DOMAIN}/api/v2/events?${params.toString()}`;

    const es = new EventSource(url, {
        headers: {
            "Authorization": `Bearer ${TOKEN}`
        }
    });

    // Traiter les événements réels
    for (const type of ["user.created", "user.updated", "user.deleted"]) {
        es.addEventListener(type, (msg) => {
            const payload = JSON.parse(msg.data);
            console.log(`Received ${type}:`, payload.event.id);

            // Traiter l'événement ici

            saveOffset(msg.lastEventId);
        });
    }

    // Traiter les marqueurs de progression sans données
    es.addEventListener("offset-only", (msg) => {
        saveOffset(msg.lastEventId);
    });

    // Traiter les erreurs fatales
    es.addEventListener("error", (msg) => {
        if (msg.data) {
            const errorPayload = JSON.parse(msg.data);
            console.error("Stream error:", errorPayload.error);
        }
        es.close();

        // Se reconnecter après un délai
        setTimeout(connect, 5000);
    });
}

connect();

Le package npm eventsource implémente le protocole SSE et gère automatiquement la reconnexion à l’aide de l’en-tête Last-Event-ID. Si vous utilisez une autre bibliothèque SSE, vérifiez qu’elle prend en charge la reconnexion automatique et la transmission de l’offset.

​

Réponses d’erreur

Events API renvoie des codes d’état HTTP standard lorsque la connexion ne peut pas être établie :

Code d’état	Signification
200	Connexion établie. La diffusion des événements commence.
400	Requête invalide. La valeur d’offset est mal formée ou le type d’événement demandé n’est pas pris en charge.
401	Jeton d’accès manquant ou invalide.
403	Le jeton d’accès n’inclut pas la portée read:events.
410	L’offset a expiré. Utilisez une valeur from_timestamp pour reprendre à partir d’un moment précis.
429	Limite de débit dépassée. Attendez, puis réessayez en utilisant l’intervalle indiqué dans l’en-tête Retry-After.

​

En savoir plus

• Catalogue d’événements
• Créer un Event Stream
• Pratiques exemplaires relatives aux événements
• Jetons d’accès à l’API de gestion