Events API でイベントを取り込む

Server-Sent Events (SSE) ベースの Events API を使用して、任意のタイミングで Auth0 からイベントを取得します。

Events API は、Event Streams に代わるプル型の手段です。Auth0 が送信先にイベントをプッシュする代わりに、アプリケーションが GET /api/v2/events への長時間維持する接続を開き、Server-Sent Events (SSE) ストリームとしてイベントを受け取ります。いつ接続するか、切断後にどのように再開するか、どのくらいの速度でイベントを取り込むかは、すべてアプリケーション側で制御できます。

このアプローチは、次のような場合に役立ちます。

• webhook エンドポイントを用意せずに、自分のペースでイベントを処理したい。
• バックフィルや復旧のために、特定の時点からイベントを再生したい。
• プッシュ型の配信よりもポーリングを好むシステムと統合したい。

​

Events API の仕組み

アプリケーションが Events API に接続すると、SSE メッセージのストリームを受信します。各メッセージには、オフセット として機能する id フィールドが含まれます。接続が切断された場合、アプリケーションは再接続し、最後に受信した オフセット を渡します。Auth0 はその位置から配信を再開するため、イベントが失われることはありません。

SSE ストリームには、次のメッセージタイプが含まれます。

Message type	Purpose
:connected	接続が確立されたことを示します。これはデータイベントではなく、SSE のコメントです。
retry: <ms>	切断後に再接続するまで、どれくらい待機するかを SSE クライアントに伝えます。
event: <type> (for example, user.created)	data フィールドに完全な ペイロード を含む実際のイベントです。
event: offset-only	一定間隔 (ハートビート の頻度) で送信される進行マーカーです。イベントデータを配信せずに オフセット を更新します。
: followed by text (for example, : heartbeat)	プロキシやロードバランサーがアイドル状態の接続を閉じないようにするための keep-alive コメントです。対応は不要です。
event: error	終端エラーです。このメッセージの後、ストリームは閉じます。

​

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

​

前提条件

始める前に、以下を用意してください。

• Events が有効化されている Auth0 テナント。利用可能な Event Stream 接続数は、ご利用のプランによって異なります。

  プラン	接続上限
  Free	1
  Self-service	4
  Enterprise	8

• read:events スコープを持つ Management API アクセストークン。詳しくは、Management API Access Tokens をご覧ください。

​

Events API に接続する

テナントの events エンドポイントへの SSE 接続を確立します。次の例では curl を使用します。

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

​

クエリパラメータ

クエリパラメータを使用して、ストリームを絞り込んだり、再開したりできます。

Parameter	Type	Description
from	string	以前の id フィールドで返されたオフセットです。このオフセットの直後から配信が再開されます。
from_timestamp	string	ISO 8601 形式のタイムスタンプです。この時刻以降に発生したイベントを返します。from とは同時に使用できません。初期設定や、既知の時点からイベントを再生する場合に最適です。継続的に受信する場合は、オフセットのほうがより正確なため、from を使って再開することを推奨します。
event_type	string	含めるイベントタイプです。種類ごとにこのパラメータを繰り返して指定します (例: 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"

​

切断後の再開

SSE 接続は、ネットワークの問題、トークンの有効期限切れ、サーバー側での接続の切り替え (Auth0 では負荷分散のため、通常は数分ごとに定期的に接続を閉じます) など、さまざまな理由で切断されることがあります。標準的な SSE クライアントライブラリは、再接続時に最後のオフセットを送信することで、こうした切断を透過的に処理します。

再接続時にオフセットを指定する方法は 2 つあります。

• Last-Event-ID ヘッダー — 標準的な SSE の再接続メカニズムです。ほとんどの SSE クライアントライブラリは、再接続時にこのヘッダーを自動的に設定します。
• from query parameter — クライアントが Last-Event-ID ヘッダーをサポートしていない場合は、こちらを使用します。

両方が指定されている場合は、Last-Event-ID ヘッダーが優先されます。

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"

すべてのメッセージ (offset-only メッセージを含む) の最新の id 値を永続ストレージに保存してください。アプリケーションが再起動した場合は、保存したオフセットを使って中断した箇所から配信を再開します。

​

メッセージの種類を処理

​

実際のイベント

event フィールドが既知のイベントタイプ (たとえば user.created) に一致するメッセージには、data フィールドにイベントの完全なペイロードが含まれます。JSON を解析し、ビジネスロジックに従ってイベントを処理してください。

​

オフセットのみのメッセージ

Auth0 は、ストリーム内の位置を進めるために、一定間隔 (ハートビートの頻度) で offset-only メッセージを送信します。これらのメッセージにはイベント ペイロード は含まれません。受信したら保存しているオフセットを更新してください。そうすることで、今後再接続した際に、すでに通過したイベントが再送されるのを防げます。

​

エラーメッセージ

event: error メッセージは、オフセットの有効期限切れやサーバー側の問題など、回復不能な問題を示します。このメッセージを受信すると、ストリームは終了します。アプリケーションではエラーを記録したうえで、適切なオフセットまたは新しい from_timestamp を指定して再接続する必要があります。

​

ハートビート

: で始まる行は、ハートビート用のSSEコメントです。これにより、プロキシやロードバランサーを経由しても接続を維持できます。特別な処理は必要ありません。

​

サーバー側での接続の切り替え

Auth0 では、負荷分散のために SSE 接続を定期的に切断します (通常は数分ごと) 。これは想定された動作であり、エラーではありません。標準的な SSE クライアントライブラリ (eventsource npm パッケージを含む) は、Last-Event-ID ヘッダーを使って自動的に再接続するため、アプリケーションはイベントを取りこぼすことなく正しいオフセットから再開できます。

カスタムの SSE クライアントを実装する場合は、最新のオフセットを保持し、その値を使って再接続することで、接続の切断に適切に対応できるようにしてください。

​

コンシューマーを実装する

以下の Node.js の例では、イベントを処理し、オフセットをファイルに保存する最小限の Events API コンシューマーを示しています。

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

    // 実際のイベントを処理する
    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);

            // ここでイベントを処理する

            saveOffset(msg.lastEventId);
        });
    }

    // オフセットのみの進捗マーカーを処理する
    es.addEventListener("offset-only", (msg) => {
        saveOffset(msg.lastEventId);
    });

    // 終端エラーを処理する
    es.addEventListener("error", (msg) => {
        if (msg.data) {
            const errorPayload = JSON.parse(msg.data);
            console.error("Stream error:", errorPayload.error);
        }
        es.close();

        // 一定時間後に再接続する
        setTimeout(connect, 5000);
    });
}

connect();

eventsource npm パッケージは SSE プロトコルを実装しており、Last-Event-ID ヘッダーを使って自動的に再接続します。別の SSE ライブラリを使用する場合は、自動再接続とオフセットの引き継ぎに対応していることを確認してください。

​

エラーレスポンス

接続を確立できない場合、Events API は標準的な HTTP ステータスコードを返します。

ステータスコード	意味
200	接続が確立されました。イベントのストリーミングが開始されます。
400	無効なリクエストです。オフセット の値の形式が正しくないか、要求されたイベントタイプはサポートされていません。
401	アクセストークンがないか、無効です。
403	アクセストークンに read:events スコープが含まれていません。
410	オフセット の有効期限が切れています。特定の時点から再開するには、from_timestamp の値を使用します。
429	レート制限を超過しています。Retry-After ヘッダーの値で指定された時間だけ待ってから、再試行してください。

​

詳細

• イベントカタログ
• イベントストリームを作成する
• イベントのベストプラクティス
• Management API Access Tokens