> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.id.me/shared-signals-framework/fraud-event-notifications/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.id.me/_mcp/server. # Fraud event notifications > Register your application to receive ID.me Shared Signals Framework (SSF) security events via HTTPS push delivery. # Registration overview ID.me requires two bits of information to create a stream: 1. Receiver URL: The public URL to which ID.me should stream events.\ Example: `https://example.com/api/v1/events` 2. Audience String: What to use as the value of the aud claim for events.\ Example: `http://example.com` > **Note** > > ID.me uses a manual onboarding process for stream registration rather than the SSF Stream Management API (`POST /ssf/stream`) defined in the SSF specification. To register, send an email to [customersupport@id.me](mailto:customersupport@id.me) with your Receiver URL and Audience String. Our team will confirm registration and provide the `iss` value (`https://events.id.me`) and any additional configuration details needed to begin receiving events. # Transmission overview The following steps represent the transmission flow. #### Transmit supported events ID.me will begin transmitting supported events to the `receiver url`. Events will be signed by the private key corresponding to the public key published at the ID.me SSF JWKS URL. Events will not be encrypted. Exactly one event will be included in each request. #### Receive events The receiver will receive the events from ID.me as an HTTP request and respond with a 2xx HTTP code to confirm the request was successfully received. If ID.me receives an error code, event transmission will be automatically retried in accordance with preset retry logic (default: 3 retries, then abort). #### Verify signature Parse the `iss` claim from the unverified token header or payload, then use it to locate and fetch the corresponding public key from the ID.me SSF JWKS URL. Verify the event signature using that public key, then confirm that the `iss` value matches `https://events.id.me` exactly. This confirms that the event was transmitted by ID.me. #### Parse aud claim The receiver should then verify that the event is intended for it by parsing the `aud` claim and ensuring that it matches the Audience URL provided during the registration step (Step 1 above) exactly. #### Process the event After verifying the signature, issuer, and audience, the receiver can proceed to processing the event. The ID.me transmitter does not expect any acknowledgement that the event was successfully validated, parsed, or processed. # Key information A private key will be used to sign all event tokens. A corresponding public key will be published at the following locations. > **Note** > > These JWKS URLs use a custom path structure and do not follow the standard `.well-known` URI convention (RFC 8615). **`Production`** ```vbscript-html Production https://events.id.me/oid/ssf/.well-known/jwks ``` **`ID.me Labs Environment (sandbox)`** ```vbscript-html ID.me Labs Environment (sandbox) https://events.idmelabs.com/oid/ssf/.well-known/jwks ``` Keys will use the RS256 algorithm (RSASSA-PKCS1-v1\_5 using SHA-256). ```json { "kty": "RSA", "n": "p9t3AF34dOTW1xChHBwz09ZlVE-U- 0_quIUDALqP4ggfIFYKbO_wG2he9wSY2XgmyWVoxlpIM_sUZhvoVyouZUQyxxnW96xt6w16lm2D12dy5jP0Y5GLrAn0PiQVDgh0729x0QwW6PwKyZjEzUgKuL9hwcZeRrk62t687dikchLlDHOgBqsDUu17135rX7Mt9BwdxAu4IG6qTO19o99bzVqfD4K1-nwZKDUl92u7IuSCHkYig8guqA0VJ2vzX7Zh7sspIGP-WQGKJgQZYP422pHCyAWzdHUnCLXPIbAnvZOHPwRbvW4UH9LoPPgmATQm3JgVVcJ7s4aGpyX7a-hbKQ", "e": "AQAB", "alg": "RS256", "kid": "9e22e276-d3a4-4a69-ad08-d26cf5b4ca19", "use": "sig" } ``` # Supported events ID.me supports six events that are part of the RISC specification. ## Expected volume The volume of the events varies from customer to customer. Please work with our team to develop an estimate of the frequency and volume of events. The table below shows a brief description of the supported events. The next section describes details of ID.me's implementation of these events. | Number | Event Type | Definition | Status | | ------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | 1 | **Account Disabled** `https://schemas.openid.net/secevent/risc/event-type/account-disabled` | This event is fired when an ID.me account is suspended for any reason | Live | | 2 | **Account Enabled** `https://schemas.openid.net/secevent/risc/event-type/account-enabled` | This event is fired when an ID.me account is reinstated, for example, as a result of a recovery process or negative fraud investigation | Live | | 3 | **Account Credential Change Required** `https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required` | This event is fired when an ID.me authority determines that the account owner must reset their password | Available upon request | | 4 | **Account Purged** `https://schemas.openid.net/secevent/risc/event-type/account-purged` | This event is fired when a Member's ID.me account is permanently deleted | Available upon request | | 5 | **Recovery Activated** `https://schemas.openid.net/secevent/risc/event-type/recovery-activated` | Events are fired when an `actor` initiates the process to recover their account (i.e., password reset, MFA recovery) | Available upon request | | 6 | **Recovery Information Changed** `https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed` | This event is fired when an `actor` updates the authenticator(s) on their ID.me account | Available upon request | # Event specifications ## Default event specifications All events will have the following: **HTTP request** | Event | Description | | ----------------------- | ------------------------------------------- | | Content-Type (required) | Will always be `"application/secevent+jwt"` | **Standard SET claims** The following will adhere to SET specifications. | Claim | Description | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | jti | Will be a random unique identifier for the token | | iss | Will always be `"https://events.id.me"` | | iat | Will always be the timestamp of the token's issuance | | aud | Will always be the Audience String supplied by the receiver during registration. This may differ from the Receiver URL. Example: `"http://example.com"` | | sub\_id | Identifies the subject of the event. Subject identification will be provided in both the header and the body, for convenience and compatibility, in accordance with the SSF spec implementer's draft 2. sub\_id will always be in the `iss_sub` format: `{"format": "iss_sub", "iss": "https://events.id.me", "sub": ""}` — **format** will always be `"iss_sub"`, **iss** will always be `"https://events.id.me"`, **sub** will always be the UUID for the subject ID.me account | | events | The event, keyed by the event type. There will always be exactly one event per HTTP Request. | > **Additional information** > > * Subject will be provided in both the header and the body, for convenience and compatibility > * Subject will always be in the `iss_sub` format: `{"format": "iss_sub", "iss": "https://events.id.me", "sub": ""}` > * **format** will always be `"iss_sub"` > * **iss** will always be `"https://events.id.me"` > * **sub** will always be the UUID for the subject ID.me account The following is a complete example of the full JWT structure, including the top-level `sub_id` claim: **`Complete JWT structure`** ```json Complete JWT structure { "iss": "https://events.id.me", "jti": "756E69717565206964656E746966696572", "iat": 1508184845, "aud": "636C69656E745F6964", "sub_id": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-1234" }, "events": { "": { "subject": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-1234" } } } } ``` ## Individual event specifications ### Account disabled This event is fired when an ID.me account is suspended for any reason. **Properties** | Key | Description | Allowable Values | | ------ | ------------------------------- | ------------------- | | reason | Reason the account was disabled | `duplicate_account` | ```json { "iss": "https://events.id.me", "jti": "756E69717565206964656E746966696572", "iat": 1508184845, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/account-disabled": { "subject": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-1234" }, "reason": "duplicate_account" } } } ``` ### Account enabled This event is fired when an ID.me account is reinstated, for example, as a result of a recovery process or negative fraud investigation. **Properties** | Key | Description | Allowable Values | | ------ | --------------------------------- | ------------------- | | reason | Reason the account was reinstated | `duplicate_account` | **`Example object`** ```json Example object { "iss": "https://events.id.me", "jti": "756E69717565206964656E746966696572", "iat": 1508184845, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/account-enabled": { "subject": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-1234" }, "reason": "duplicate_account" } } } ``` ### Account credential change required This event is fired when an ID.me authority determines that the account owner must reset their password. **Properties** | Key | Description | Allowable Values | | ------ | -------------------------------------- | ---------------- | | reason | Reason a credential change is required | TBD | **`Example object`** ```json Example object { "iss": "https://events.id.me", "jti": "756E69717565206964656E746966696572", "iat": 1508184845, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required": { "subject": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-1234" } } } } ``` ### Account purged This event is fired when a Member's ID.me account is permanently deleted. **RISC Spec** Signals that the account identified by the subject has been permanently deleted. URI: `https://schemas.openid.net/secevent/risc/event-type/account-purged` **When it's fired** * User-Requested Erasure via GDPR/CCPA right-to-erasure flows * PII Retention Expiry (e.g., 3 years after account closure) * Biometric Retention Expiry (e.g., 35 months post-inactivity) **Properties** The RISC spec defines no normative properties for this event. The following fields are ID.me extensions. | Key | Description | Allowable Values | | ------ | ----------------------------------------- | ------------------------------------- | | actor | Which type of entity initiated the action | `system`, `user`, `admin` | | reason | Reason the account was purged | `user_requested`, `retention_expired` | **`Example object`** ```json Example object { "iss": "https://events.id.me", "jti": "756E69717565206964656E746966696572", "iat": 1508184845, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/account-purged": { "subject": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-1234" }, "reason": "retention_expired" } } } ``` ### Recovery activated This event is fired when a user initiates the process to recover their account (examples: password reset, MFA recovery). **RISC Spec** Signals that the account identified by the subject activated a recovery flow. URI: `https://schemas.openid.net/secevent/risc/event-type/recovery-activated` **When it fires** * Forgot Password flow initiation (user clicks "Forgot password") * Forgot MFA flow (lost device / de-registered authenticator) * Support-Initiated Reset or account unlock by an agent * Fraud Rule automatically resets an authenticator **Properties** | Key | Description | Allowable Values | | ----- | ----------------------------------------- | ---------------------------------------- | | actor | Which type of entity initiated the action | `system`, `user`, `admin` | | type | Type of recovery flow | `password`, `mfa`, `support_force_reset` | **`Example object`** ```json Example object { "iss": "https://events.id.me", "jti": "756E69717565206964656E746966696572", "iat": 1508184845, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/recovery-activated": { "subject": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-11223" }, "actor": "admin", "type": "password" } } } ``` ### Recovery information changed This event is fired when a user updates the authenticator(s) on their ID.me account. **RISC Spec:** Recovery Information Changed signals that the account identified by the subject has changed some of its recovery information. For example a recovery email address was added or removed. URI: `https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed` **Properties** | Key | Description | Allowable Values | | ----- | -------------------------------------------- | --------------------------- | | actor | Which entity initiated the action | `system`, `user`, `admin` | | type | Which recovery information attribute changed | `phone`, `email`, `address` | **`Example object`** ```json Example object { "iss": "https://events.id.me", "jti": "756E69717565206964656E746966696572", "iat": 1508184845, "aud": "636C69656E745F6964", "events": { "https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed": { "subject": { "format": "iss_sub", "iss": "https://events.id.me", "sub": "user-uuid-11223" }, "actor": "admin", "type": "email" } } } ``` > Register your application to receive ID.me Shared Signals Framework (SSF) security events via HTTPS push delivery. ## Docs - [Overview](https://docs.id.me/guides/shared-signals-framework/ssf-overview.md): Overview of the ID.me Shared Signals Framework (SSF) for near real-time exchange of security events between ID.me and relying parties.