Skip to navigation

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:

  1. Receiver URL: The public URL to which IDMe 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

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.

1

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.

2

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).

3

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.

4

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.

5

Process the event

After verifying the signature, issuer, and audience, the receiver can proceed to processing the event. The IDMe 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.

These JWKS URLs use a custom path structure and do not follow the standard .well-known URI convention (RFC 8615).

Production
https://events.id.me/oid/ssf/.well-known/jwks
IDMe Labs Environment (sandbox)
https://events.idmelabs.com/oid/ssf/.well-known/jwks
Each environment has its own keys

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 kid in the token header. A JWKS may contain more than one key, for example during key rotation.
  • If a token arrives with a kid that is not in your cached JWKS, refetch the JWKS from the same environment before rejecting the token.
  • Do not hard-code kid values; they change when keys rotate.

Keys will use the RS256 algorithm (RSASSA-PKCS1-v1_5 using SHA-256).

{
"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

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.

NumberEvent TypeDefinitionStatus
1Account Disabled https://schemas.openid.net/secevent/risc/event-type/account-disabledThis event is fired when an IDMe account is suspended for any reasonLive
2Account Enabled https://schemas.openid.net/secevent/risc/event-type/account-enabledThis event is fired when an IDMe account is reinstated, for example, as a result of a recovery process or negative fraud investigationLive
3Account Credential Change Required https://schemas.openid.net/secevent/risc/event-type/account-credential-change-requiredThis event is fired when an IDMe authority determines that the account owner must reset their passwordLive
4Account Purged https://schemas.openid.net/secevent/risc/event-type/account-purgedThis event is fired when a Member’s IDMe account is permanently deletedLive
5Recovery Activated https://schemas.openid.net/secevent/risc/event-type/recovery-activatedEvents are fired when an actor initiates the process to recover their account (i.e., password reset, MFA recovery)Live
6Recovery Information Changed https://schemas.openid.net/secevent/risc/event-type/recovery-information-changedThis event is fired when an actor updates the authenticator(s) on their IDMe accountLive

Event specifications

Default event specifications

All events will have the following:

HTTP request

EventDescription
Content-Type (required)Will always be "application/secevent+jwt"

Standard SET claims

The following will adhere to SET specifications.

ClaimDescription
jtiWill be a random unique identifier for the token
issWill always be "https://events.id.me"
iatWill always be the timestamp of the token’s issuance
audWill always be the Audience String supplied by the receiver during registration. This may differ from the Receiver URL. Example: "http://example.com"
sub_idIdentifies 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": "<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
eventsThe 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": "<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

The following is a complete example of the full JWT structure, including the top-level sub_id claim:

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": {
"<event-type-uri>": {
"subject": {
"format": "iss_sub",
"iss": "https://events.id.me",
"sub": "user-uuid-1234"
}
}
}
}

Individual event specifications

Account disabled

This event is fired when an IDMe account is suspended for any reason.

Properties

KeyDescriptionAllowable Values
reasonReason the account was disabledduplicate_account

See Suspension reason codes for the full list of current reason codes.

{
"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 IDMe account is reinstated, for example, as a result of a recovery process or negative fraud investigation.

Properties

KeyDescriptionAllowable Values
reasonReason the account was reinstatedduplicate_account
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 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.

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 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.

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

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.

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

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.

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

Appendix

Expand a section below for details.

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 POST request and the same Content-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: always true
    • synthetic_source: identifies the test generator
    • synthetic_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.

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

  1. The receiver reads the token from the wrong place. It looks for the token in an Authorization: Bearer header, 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.
  2. The request body is empty by the time it reaches the parser. A gateway or framework drops bodies with the application/secevent+jwt content type, or a filter consumes the request body before the handler reads it.
  3. The request was not an IDMe event, for example a health check, a manual test, or traffic from your own mock or test sender.

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

  1. 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.
  2. 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.
  3. 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 kid arrives.

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 kid is published by one IDMe environment but not by the JWKS your receiver uses: your receiver is configured with the wrong JWKS URL.
  • The kid matches no IDMe environment: the event did not come from IDMe.
  • The kid is 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.