Shared Signals FrameworkReal Time Events

Fraud event notifications

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

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, email your Customer Success Manager (CSM) with your Receiver URL and Audience String. Your CSM 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

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.

2

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

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

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

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

1{
2     "kty": "RSA",
3     "n": 
4     "p9t3AF34dOTW1xChHBwz09ZlVE-U- 0_quIUDALqP4ggfIFYKbO_wG2he9wSY2XgmyWVoxlpIM_sUZhvoVyouZUQyxxnW96xt6w16lm2D12dy5jP0Y5GLrAn0PiQVDgh0729x0QwW6PwKyZjEzUgKuL9hwcZeRrk62t687dikchLlDHOgBqsDUu17135rX7Mt9BwdxAu4IG6qTO19o99bzVqfD4K1-nwZKDUl92u7IuSCHkYig8guqA0VJ2vzX7Zh7sspIGP-WQGKJgQZYP422pHCyAWzdHUnCLXPIbAnvZOHPwRbvW4UH9LoPPgmATQm3JgVVcJ7s4aGpyX7a-hbKQ",
5     "e": "AQAB",
6     "alg": "RS256",
7     "kid": "9e22e276-d3a4-4a69-ad08-d26cf5b4ca19",
8     "use": "sig"
9}

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

NumberEvent TypeDefinitionStatus
1Account Disabled https://schemas.openid.net/secevent/risc/event-type/account-disabledThis event is fired when an ID.me account is suspended for any reasonLive
2Account Enabled https://schemas.openid.net/secevent/risc/event-type/account-enabledThis event is fired when an ID.me 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 ID.me 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 ID.me 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 ID.me 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 ID.me 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 ID.me account

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

Complete JWT structure
1{
2  "iss": "https://events.id.me",
3  "jti": "756E69717565206964656E746966696572",
4  "iat": 1508184845,
5  "aud": "636C69656E745F6964",
6  "sub_id": {
7    "format": "iss_sub",
8    "iss": "https://events.id.me",
9    "sub": "user-uuid-1234"
10  },
11  "events": {
12    "<event-type-uri>": {
13      "subject": {
14        "format": "iss_sub",
15        "iss": "https://events.id.me",
16        "sub": "user-uuid-1234"
17      }
18    }
19  }
20}

Individual event specifications

Account disabled

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

Properties

KeyDescriptionAllowable Values
reasonReason the account was disabledduplicate_account
1{
2  "iss": "https://events.id.me",
3  "jti": "756E69717565206964656E746966696572",
4  "iat": 1508184845,
5  "aud": "636C69656E745F6964",
6  "events": {
7    "https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
8      "subject": {
9        "format": "iss_sub",
10        "iss": "https://events.id.me",
11        "sub": "user-uuid-1234"
12      },
13      "reason": "duplicate_account"
14    }
15  }
16}

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

KeyDescriptionAllowable Values
reasonReason the account was reinstatedduplicate_account
Example object
1{
2  "iss": "https://events.id.me",
3  "jti": "756E69717565206964656E746966696572",
4  "iat": 1508184845,
5  "aud": "636C69656E745F6964",
6  "events": {
7    "https://schemas.openid.net/secevent/risc/event-type/account-enabled": {
8      "subject": {
9        "format": "iss_sub",
10        "iss": "https://events.id.me",
11        "sub": "user-uuid-1234"
12      },
13      "reason": "duplicate_account"
14    }
15  }
16}

Account credential change required

This event is fired when an ID.me authority determines that the account owner must reset their password.

Properties

KeyDescriptionAllowable Values
reasonReason a credential change is requiredTBD
Example object
1{
2  "iss": "https://events.id.me",
3  "jti": "756E69717565206964656E746966696572",
4  "iat": 1508184845,
5  "aud": "636C69656E745F6964",
6  "events": {
7    "https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required": {
8      "subject": {
9        "format": "iss_sub",
10        "iss": "https://events.id.me",
11        "sub": "user-uuid-1234"
12      }
13    }
14  }
15}

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.

KeyDescriptionAllowable Values
actorWhich type of entity initiated the actionsystem, user, admin
reasonReason the account was purgeduser_requested, retention_expired
Example object
1{
2  "iss": "https://events.id.me",
3  "jti": "756E69717565206964656E746966696572",
4  "iat": 1508184845,
5  "aud": "636C69656E745F6964",
6  "events": {
7    "https://schemas.openid.net/secevent/risc/event-type/account-purged": {
8      "subject": {
9        "format": "iss_sub",
10        "iss": "https://events.id.me",
11        "sub": "user-uuid-1234"
12      },
13      "reason": "retention_expired"
14    }
15  }
16}

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

KeyDescriptionAllowable Values
actorWhich type of entity initiated the actionsystem, user, admin
typeType of recovery flowpassword, mfa, support_force_reset
Example object
1{
2  "iss": "https://events.id.me",
3  "jti": "756E69717565206964656E746966696572",
4  "iat": 1508184845,
5  "aud": "636C69656E745F6964",
6  "events": {
7    "https://schemas.openid.net/secevent/risc/event-type/recovery-activated": {
8      "subject": {
9        "format": "iss_sub",
10        "iss": "https://events.id.me",
11        "sub": "user-uuid-11223"
12      },
13      "actor": "admin",
14      "type": "password"
15    }
16  }
17}

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

KeyDescriptionAllowable Values
actorWhich entity initiated the actionsystem, user, admin
typeWhich recovery information attribute changedphone, email, address
Example object
1{
2  "iss": "https://events.id.me",
3  "jti": "756E69717565206964656E746966696572",
4  "iat": 1508184845,
5  "aud": "636C69656E745F6964",
6  "events": {
7    "https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed": {
8      "subject": {
9        "format": "iss_sub",
10        "iss": "https://events.id.me",
11        "sub": "user-uuid-11223"
12      },
13      "actor": "admin",
14      "type": "email"
15    }
16  }
17}