Registration overview

ID.me requires two bits of information to create a stream:

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

It is the responsibility of the receiver organization to provide this information to ID.me in an email to your Customer Success Manager (CSM)

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

The receiver should verify the signature on the event, parse the iss claim and ensure that it 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.

Production

1 https://events.id.me/oid/ssf/.well-known/jwks

External integration (sandbox)

1 https://events.idmelabs.com/oid/ssf/.well-known/jwks

Keys will use the RSA SHA256 algorithm for signing.

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.

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	Live
4	Account Purged https://schemas.openid.net/secevent/risc/event-type/account-purged	This event is fired when an `actor` takes action	Live
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)	Live
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	Live

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 receiver URL supplied by the receiver during registration. 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: subject{format, iss,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: subject{format,iss,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

Individual event specifications

Account disabled

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

Properties

reason

Example object

1 {
2   "iss": "https://events.id.me",
3   "jti": "756E69717565206964656E746966696572",
4   "iat": 1508184845,
5   "exp": 1728573520,
6   "aud": "636C69656E745F6964",
7   "events": {
8     "https://schemas.openid.net/secevent/risc/event-type/\
9     account-disabled": {
10       "subject": {
11         "format": "iss_sub",
12         "iss": "https://idp.id.me/",
13         "sub": "user-uuid-1234",
14       },
15       "reason": "Duplicate Account",
16     }
17   }
18 }

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

reason

Example object

1 {
2   "iss": "https://events.id.me",
3   "jti": "756E69717565206964656E746966696572",
4   "iat": 1508184845,
5   "exp": 1728573520,
6   "aud": "636C69656E745F6964",
7   "events": {
8     "https://schemas.openid.net/secevent/risc/event-type/\
9     account-enabled": {
10       "subject": {
11         "format": "iss_sub",
12         "iss": "https://idp.id.me/",
13         "sub": "user-uuid-1234",
14       },
15       "reason": "Duplicate Account"
16     }
17   }
18 }

Account credential change required

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

Properties

reason

Example object

1 {
2   "iss": "https://events.id.me",
3   "jti": "756E69717565206964656E746966696572",
4   "iat": 1508184845,
5   "exp": 1728573520,
6   "aud": "636C69656E745F6964",
7   "events": {
8     "https://schemas.openid.net/secevent/risc/event-type/\
9     account-credential-change-required": {
10       "subject": {
11         "format": "iss_sub",
12         "iss": "https://idp.id.me",
13         "sub": "user-uuid-1234",
14       },
15     }
16   }
17 }

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

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

1 {
2   "iss": "https://events.id.me",
3   "jti": "756E69717565206964656E746966696572",
4   "iat": 1508184845,
5   "exp": 1728573520,
6   "aud": "636C69656E745F6964",
7   "events": {
8     "https://schemas.openid.net/secevent/risc/event-type/account-purged": {
9       "subject": {
10         "format": "iss_sub",
11         "iss": "https://idp.id.me",
12         "sub": "user-uuid-1234"
13       }
14       "reason": "retention_expired"
15     }
16   }
17 }

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

1 {
2   "iss": "https://events.id.me",
3   "jti": "756E69717565206964656E746966696572",
4   "iat": 1508184845,
5   "exp": 1728573520,
6   "aud": "636C69656E745F6964",
7   "events": {
8     "https://schemas.openid.net/secevent/risc/event-type/recovery-activated": {
9       "subject": {
10         "format": "iss_sub",
11         "iss": "https://idp.id.me",
12         "sub": "user-uuid-11223"
13       }
14       "actor": "admin",
15       "type": "password"
16     }
17   }
18 }

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

1 {
2   "iss": "https://events.id.me",
3   "jti": "756E69717565206964656E746966696572",
4   "iat": 1508184845,
5   "exp": 1728573520,
6   "aud": "636C69656E745F6964",
7   "events": {
8 "https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed": {
9       "subject": {
10         "format": "iss_sub",
11         "iss": "https://idp.id.me",
12         "sub": "user-uuid-11223"
13       }
14       "actor": "admin",
15       "type": "password"
16     }
17   }
18 }