Events API は、Event Stream に代わるプルベースの手段を提供します。Auth0 がイベントを送信先にプッシュする代わりに、アプリケーションは GET /api/v2/events への長時間接続を確立し、Server-Sent Events (SSE) ストリームとしてイベントを受信します。接続するタイミング、切断後の再開方法、イベントを消費する速度は、すべて制御できます。
このアプローチは、次のような場合に役立ちます。
Webhook エンドポイントを用意せずに、自分のペースでイベントを処理する必要がある場合。
バックフィルや復旧のために、特定の時点からイベントを再生する必要がある場合。
プッシュベースの配信ではなく、ポーリングを前提とするシステムと統合する場合。
アプリケーションが 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)プロキシやロードバランサーがアイドル状態の接続を閉じるのを防ぐためのキープアライブコメントです。対応は不要です。 event: error終端エラーです。このメッセージの後、ストリームは閉じられます。
: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":"jane@example.com"}}}} 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":"jane.doe@example.com"}}}}
開始する前に、次のものを用意してください。
Events が有効になっている Auth0 テナント。利用可能な Event Stream 接続数は、ご利用のプランによって異なります。
プラン 接続上限 Free 1 Self-service 4 Enterprise 8
read:events スコープを持つ Management API アクセストークン。詳細については、Management 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 fromstring 以前の id フィールドで返されたオフセットです。配信はこのオフセットの直後から再開されます。 from_timestampstring ISO 8601 タイムスタンプです。この時刻以降に発生したイベントを返します。from とは同時に指定できません。初期設定や、既知の時点からイベントを再生する場合に適しています。継続的に取り込む場合は、オフセットのほうがより正確なため、from で再開することを推奨します。 event_typestring 含めるイベントタイプです。タイプごとにこのパラメーターを繰り返し指定します (例: 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 headerfrom query parameterLast-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無効なリクエストです。offset の値の形式が不正か、要求されたイベントタイプがサポートされていません。 401アクセストークンがないか無効です。 403アクセストークンに read:events スコープが含まれていません。 410offset の有効期限が切れています。特定の時点から再開するには、from_timestamp の値を使用してください。429レート制限を超過しました。Retry-After ヘッダーで指定された時間だけ待機してから、再試行してください。
認証
ユーザー管理
カスタマイズ
Auth0 AI
プラットフォーム