Fraud event notifications
IDMe fraud event notifications are delivered in alignment with RFC 8935: Push-Based Security Event Token (SET) Delivery Using HTTP. Each notification is an RFC 8417 Security Event Token: a JWT signed with RS256 (not encrypted) that carries an OpenID RISC event type. IDMe pushes each token to your receiver as the raw HTTP POST body with Content-Type: application/secevent+jwt.
Registration overview
IDMe requires two bits of information to create a stream:
- Receiver URL: The public URL to which IDMe should stream events.
Example:https://example.com/api/v1/events - Audience String: What to use as the value of the aud claim for events.
Example:http://example.com
IDMe 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 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
IDMe 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 IDMe 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 IDMe as an HTTP request and respond with a 2xx HTTP code to confirm the request was successfully received. If IDMe 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 IDMe 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 IDMe.
Key information
A private key will be used to sign all event tokens. A corresponding public key will be published at the following locations.
These JWKS URLs use a custom path structure and do not follow the standard .well-known URI convention (RFC 8615).
The IDMe Labs and Production environments sign events with different keys, and each publishes only its own keys at its own JWKS URL. Keys are never shared between environments, so an event signed in Labs can only be verified with the Labs JWKS, and an event signed in Production can only be verified with the Production JWKS.
- Configure your non-production receiver with the Labs JWKS URL and your production receiver with the Production JWKS URL.
- Select the verification key by matching the
kidin the token header. A JWKS may contain more than one key, for example during key rotation. - If a token arrives with a
kidthat is not in your cached JWKS, refetch the JWKS from the same environment before rejecting the token. - Do not hard-code
kidvalues; they change when keys rotate.
Keys will use the RS256 algorithm (RSASSA-PKCS1-v1_5 using SHA-256).
Supported events
IDMe 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 IDMe’s implementation of these events.
Event specifications
Default event specifications
All events will have the following:
HTTP request
Standard SET claims
The following will adhere to SET specifications.
- Subject will be provided in both the header and the body, for convenience and compatibility
- Subject will always be in the
iss_subformat:{"format": "iss_sub", "iss": "https://events.id.me", "sub": "<uuid>"}- format will always be
"iss_sub" - iss will always be
"https://events.id.me" - sub will always be the UUID for the subject IDMe account
- format will always be
The following is a complete example of the full JWT structure, including the top-level sub_id claim:
Individual event specifications
Account disabled
This event is fired when an IDMe account is suspended for any reason.
Properties
See Suspension reason codes for the full list of current reason codes.
Account enabled
This event is fired when an IDMe account is reinstated, for example, as a result of a recovery process or negative fraud investigation.
Properties
Account credential change required
This event is fired when an IDMe authority determines that the account owner must reset their password.
Properties
The RISC spec defines no normative properties for this event, and IDMe does not add any extensions.
Account purged
This event is fired when a Member’s IDMe 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, and IDMe does not add any extensions.
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
The RISC spec defines no normative properties for this event, and IDMe does not add any extensions.
Recovery information changed
This event is fired when a user updates the authenticator(s) on their IDMe 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
The RISC spec defines no normative properties for this event, and IDMe does not add any extensions.
Appendix
Expand a section below for details.
Testing with synthetic events in IDMe Labs
IDMe can send synthetic (test) fraud event notifications to your non-production receiver from the IDMe Labs environment, so you can validate your integration end to end before going live. Synthetic events are not available in Production.
Requesting synthetic events
Contact customersupport@id.me and include:
- the supported event types you want to receive (see Supported events);
- whether you want them sent on a recurring schedule (for example, every 10 minutes), on demand, or both.
Our team will enable synthetic events for your stream in IDMe Labs and confirm when they are active.
What synthetic events look like
- They are delivered to your registered Receiver URL exactly like real events: the same HTTP
POSTrequest and the sameContent-Type: application/secevent+jwt. - They are signed with the IDMe Labs keys, so verify them with the IDMe Labs JWKS URL (see Key information).
- They use the same token format as real events. The subject is a generated test account, not a real IDMe Member.
- The event object also includes these claims, so you can tell synthetic events apart from real ones:
synthetic: alwaystruesynthetic_source: identifies the test generatorsynthetic_trigger_type:"scheduled"or"manual"
Treat any event with "synthetic": true as test traffic. Validate and acknowledge it as you would a real event, but do not take action on a real account.
Error: Invalid serialized unsecured/JWS/JWE object: Missing part delimiters
This message comes from the Nimbus JOSE library, which is common in Java receivers. It occurs only when the parsed input contains no . at all. A compact JWT is three base64url parts joined by dots, so even a damaged token that still has its dots produces a different error. A receiver that sees this error almost certainly did not parse an IDMe token.
IDMe always sends a complete three-part token as the raw request body with Content-Type: application/secevent+jwt. The token is never placed in a request header.
Likely causes, most likely first
- The receiver reads the token from the wrong place. It looks for the token in an
Authorization: Bearerheader, a JSON field, or a form parameter instead of the raw request body, parses an empty string, and fails with this error. This is the most common mistake with RFC 8935 push delivery. - The request body is empty by the time it reaches the parser. A gateway or framework drops bodies with the
application/secevent+jwtcontent type, or a filter consumes the request body before the handler reads it. - The request was not an IDMe event, for example a health check, a manual test, or traffic from your own mock or test sender.
Error: kid not found in JWKS (sometimes reported as a decryption error)
IDMe events are signed, not encrypted, so a “decryption error” here is really a signature-key lookup failure. The token parsed successfully, but the kid in its header is not in the JWKS your receiver fetched.
Likely causes, most likely first
- The receiver uses the JWKS of a different IDMe environment than the one sending. For example, IDMe Labs sends while the receiver verifies with the Production JWKS, or the reverse. See Key information.
- A mock or test sender is still delivering. If the receiver now verifies with the IDMe JWKS but a mock service keeps sending, every mock-signed event fails with this error.
- The receiver is using a cached copy of an old JWKS, such as a mock service’s keys, after switching to IDMe. Refetch the JWKS when an unknown
kidarrives.
Narrowing it down
Decode the failing token’s header (without verifying it) and compare its kid with the keys published at the IDMe Labs and Production JWKS URLs:
- The
kidis published by one IDMe environment but not by the JWKS your receiver uses: your receiver is configured with the wrong JWKS URL. - The
kidmatches no IDMe environment: the event did not come from IDMe. - The
kidis in the JWKS your receiver is configured with, but verification still fails: your receiver’s JWKS cache is stale.
If the problem persists, contact customersupport@id.me with the token header (or the full token) and the timestamp of a failing request.