Consume Events with the Events API

Pull events from Auth0 on your own schedule using the Server-Sent Events (SSE) based Events API.

The Events API provides a pull-based alternative to Event Streams. Instead of Auth0 pushing events to a destination, your application opens a long-lived connection to GET /api/v2/events and receives events as a Server-Sent Events (SSE) stream. You control when to connect, how to resume after a disconnection, and how fast to consume events.

This approach is useful when you need to:

• Process events at your own pace without standing up a webhook endpoint.
• Replay events from a specific point in time for backfill or recovery.
• Integrate with systems that prefer polling over push-based delivery.

How the Events API works

When your application connects to the Events API, it receives a stream of SSE messages. Each message includes an id field that acts as an offset. If the connection drops, your application reconnects and provides the last offset it received. Auth0 resumes delivery from that point, so no events are lost.

The SSE stream includes the following message types:

Message type	Purpose
:connected	Confirms the connection is established. This is an SSE comment, not a data event.
retry: <ms>	Tells the SSE client how long to wait before reconnecting after a disconnect.
event: <type> (for example, user.created)	A real event with full payload in the data field.
event: offset-only	A progress marker sent at regular intervals (on heartbeat frequency). Updates the offset without delivering event data.
: followed by text (for example, : heartbeat)	A keep-alive comment that prevents proxies and load balancers from closing idle connections. No action required.
event: error	A terminal error. The stream closes after this message.

Example SSE stream

: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]"}}}}

Prerequisites

Before you begin, make sure you have:

• An Auth0 tenant with Events enabled. The number of Event Stream connections available depends on your plan:

  Plan	Connection limit
  Free	1
  Self-service	4
  Enterprise	8

• A Management API access token with the read:events scope. To learn more, read Management API Access Tokens.

Connect to the Events API

Open an SSE connection to the events endpoint on your tenant. The following example uses curl:

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

Query parameters

Use query parameters to filter or resume the stream:

Parameter	Type	Description
from	string	An offset returned in a previous id field. Delivery resumes after this offset.
from_timestamp	string	An ISO 8601 timestamp. Returns events that occurred at or after this time. Mutually exclusive with from. Best used for initial setup or replaying events from a known point in time; for ongoing consumption, prefer resuming with from because offsets are more precise.
event_type	string	The event type to include. Repeat the parameter for each type (for example, 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"

Resume after a disconnection

SSE connections can drop for many reasons: network issues, token expiration, or server-side connection cycling (Auth0 periodically closes connections for load balancing — typically every few minutes). Standard SSE client libraries handle this transparently by reconnecting and sending the last offset.

There are two ways to supply the offset on reconnection:

• Last-Event-ID header — the standard SSE reconnection mechanism. Most SSE client libraries set this header automatically when reconnecting.
• from query parameter — use this when your client does not support the Last-Event-ID header.

If both are provided, the Last-Event-ID header takes precedence.

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"

Persist the latest id value from every message (including offset-only messages) to durable storage. If your application restarts, use the persisted offset to resume delivery from where you left off.

Handle message types

Real events

Messages where the event field matches a known event type (for example, user.created) contain the full event payload in the data field. Parse the JSON and process the event according to your business logic.

Offset-only messages

Auth0 sends offset-only messages at regular intervals (on the heartbeat frequency) to advance your position in the stream. These messages do not contain an event payload. Update your stored offset when you receive them so that a future reconnection does not replay events you have already passed.

Error messages

An event: error message signals a terminal issue such as an expired offset or a server-side problem. After receiving this message, the stream closes. Your application should log the error, then reconnect with the appropriate offset or a fresh from_timestamp.

Heartbeats

Lines that begin with : are SSE comments used as heartbeats. They keep the connection alive through proxies and load balancers. No processing is required.

Server-side connection cycling

Auth0 periodically closes SSE connections for load-balancing purposes (typically every few minutes). This is expected behavior, not an error. Standard SSE client libraries (including the eventsource npm package) reconnect automatically using the Last-Event-ID header, so your application resumes from the correct offset without losing events.

If you build a custom SSE client, make sure it handles connection drops gracefully by persisting the latest offset and reconnecting with it.

Implement a consumer

The following Node.js example demonstrates a minimal Events API consumer that processes events and persists the offset to a file.

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}`
        }
    });

    // Handle real events
    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);

            // Process the event here

            saveOffset(msg.lastEventId);
        });
    }

    // Handle offset-only progress markers
    es.addEventListener("offset-only", (msg) => {
        saveOffset(msg.lastEventId);
    });

    // Handle terminal errors
    es.addEventListener("error", (msg) => {
        if (msg.data) {
            const errorPayload = JSON.parse(msg.data);
            console.error("Stream error:", errorPayload.error);
        }
        es.close();

        // Reconnect after a delay
        setTimeout(connect, 5000);
    });
}

connect();

The eventsource npm package implements the SSE protocol and handles reconnection automatically using the Last-Event-ID header. If you use a different SSE library, verify that it supports automatic reconnection and offset forwarding.

Error responses

The Events API returns standard HTTP status codes when the connection cannot be established:

Status code	Meaning
200	Connection established. Events begin streaming.
400	Invalid request. The offset value is malformed or the requested event type is not supported.
401	Missing or invalid access token.
403	The access token does not include the read:events scope.
410	The offset has expired. Use a from_timestamp value to resume from a specific point in time.
429	Rate limit exceeded. Wait and retry using the interval from the Retry-After header.

Learn more

• Event Types
• Create an Event Stream
• Events Best Practices
• Management API Access Tokens