eIDs (v2)

Authenticates users using a national electronic identity document

Used when businesses need to authenticate users through government-issued eID schemes. Supports multiple eID providers (e.g. France Identité, Personalausweis) through a unified step, with routing to the appropriate provider managed by IDnow. Results are returned as a unified Verification data block.

Key features

Multi-provider support: Routes to the appropriate eID provider backend based on the user's selected method and your organisation's routing configuration.
OIDC-based authentication: Authenticates users via OpenID Connect with the eID provider.
Flexible method selection: Works with an upstream Verification method selector (v2) step, or can be pre-configured to a fixed method.
Unified Verification data block: Produces a structured record describing the eID method used, the authority, cryptographic evidence, and the assurance level achieved.

Method selection modes

The step supports two modes for determining which eID method to use:

Mode	When to use	How to configure
End-user selection	The end-user chooses their preferred eID method at runtime (e.g. from a list presented by an upstream selector step).	Place a Verification method selector (v2) step before this step. Leave `preconfigure` unset.
Customer-provided selection	The customer's backend system determines the eID method and passes it at session creation time, without any end-user selector step in the flow.	Inject an `eIDMethodSelection` datablock via the `input` field when creating the session. Leave `preconfigure` unset.
Pre-configured method	The method is fixed by the flow definition — the end-user has no choice and no runtime input is needed.	Set `preconfigure.method` in this step's configuration. No upstream selector or session input is needed.

These modes are mutually exclusive. preconfigure takes precedence over any eIDMethodSelection input. If neither is configured, flow validation will reject the flow definition — the step requires either preconfigure or an upstream eIDMethodSelection input to be wired.

Configuration

Option	Type	Required	Description
`preconfigure`	object	No	Pre-selects a fixed eID method, bypassing the need for an upstream Verification method selector step. When present, the step uses this method directly instead of reading the user's selection from the flow context.
`preconfigure.method`	string	Yes (if `preconfigure` set)	The eID method to use. Accepted values: `franceIdentite`, `personalausweis`, `lIdentiteNumeriqueLaPoste`, `spid`, `itsme`, `lithuanianMobileId`, `mojeIdPl`, `idin`, `smartId`, `mitId`, `norwegianBankId`, `estonianIdCard`, `latvianIdCard`, `lithuanianIdCard`, `finnishTrustNetwork`, `frejaEid`, `belgiumIdCard`, `edoApp`, `eParakstsMobile`, `portugueseIdCard`, `finnishHenkilokortti`, `serbianIdCard`, `swedishBankId`, `idAustria`, `chaveMovelDigital`, `oneId`.
`preconfigure.assuranceLevel`	string	No	Required assurance level for the authentication. Accepted values: `low`, `substantial`, `high`.
`preconfigure.trustFramework`	string	No	Trust framework governing the assurance level. Accepted values: `eidas`.
`enableRetry`	boolean	No	When `true`, adds a `retry` output route that can be used to handle user cancellations. Defaults to `false`.

Without preconfigure, the step reads the user's eID method selection produced by an upstream VERIFICATION_METHOD_SELECTOR:v2 step. If neither preconfigure nor an upstream selector is wired, flow validation will reject the flow definition.

Example

With an upstream Verification method selector (recommended for multi-method flows):

{}

With preconfigure (single-method flows, no selector needed):

{
  "preconfigure": {
    "method": "franceIdentite",
    "assuranceLevel": "substantial",
    "trustFramework": "eidas"
  }
}

Input data blocks

Data block	Required	Description
`eIDMethodSelection`	Conditional	Produced by an upstream `VERIFICATION_METHOD_SELECTOR:v2` step when the user selects an eID method. Required when `preconfigure` is not set.

Routes

Route	Description
`verified`	The user's identity has been successfully authenticated by the eID provider. The OIDC flow completed and the provider returned a valid identity assertion.
`not_verified`	The authentication attempt failed. The identity could not be verified — for example, the user entered an incorrect PIN or the eID provider rejected the authentication request.
`retry`	Available when `enableRetry: true`. Taken when the user clicks the Go back button. Returns a rollback transition to the retry step.

:::note User cancellation vs. retry The close button (X) in the header always aborts the session — it is not affected by enableRetry and never routes to retry. Only the Go back button (visible when enableRetry: true) takes the retry route. :::

Output data blocks

Route	Data blocks produced
`verified`	`BasicIdentity`, `ExtendedIdentity`, `Verification`
`not_verified`	`Verification`
`retry`	`Verification`

`Verification` data block

The Verification data block produced by EIDS:v2 describes the outcome of the eID authentication.

Field	Type	Description
`status`	string	Verification status. One of: `verified`, `rejected`, `aborted`, `error`, `fraudDetected`. The value `canceled` exists in the schema but is not emitted by eID flows. `fraudDetected` is emitted by the Personalausweis path when a confirmed fraud suspicion is detected.
`provider`	string	The eID provider used. `"idnow"` for Personalausweis; `null` for France Identité and eIDEasy-routed methods.
`trustFramework`	string \| null	Trust framework of the assurance level achieved (e.g. `"eidas"`). Derived from the assurance level returned by the eID provider. `null` when no assurance level is returned or the value is not recognised.
`assuranceLevel`	string \| null	Assurance level achieved (e.g. `"substantial"`). Derived from the assurance level returned by the eID provider. `null` when no assurance level is returned or the value is not recognised.
`verifiedAt`	string	ISO 8601 timestamp of the authentication.
`verificationProcessId`	string \| null	Provider transaction or session reference.
`terminationReason`	object \| null	Present when the process was aborted by the user. Contains `code` (string) and `message` (string \| null).
`methods`	array	Always contains one entry of type `eid` describing the eID method used.

When assuranceLevel is requested (via preconfigure or an upstream eIDMethodSelection), the step requests authentication at that level from the eID provider when the provider supports it. After authentication completes, the actual assurance level returned by the provider is compared against the requested level. If the returned level is absent or lower than requested, the not_verified route is taken, Verification.status is rejected, and trustFramework/assuranceLevel are null.

`methods[].eid`

Field	Type	Description
`type`	string	Always `"eid"`.
`schemeId`	string \| null	eID scheme identifier — one of the values accepted by `preconfigure.method` (e.g. `"franceIdentite"`, `"personalausweis"`, `"itsme"`). `null` if the scheme could not be determined.
`authority`	string	The issuing authority. `"Agence Nationale des Titres Sécurisés"` (France Identité) or `"Bundesministerium des Innern (BMI)"` (Personalausweis).
`countryCode`	string	ISO 3166-1 alpha-2 country code. `"FR"` or `"DE"`.
`evidence`	array	Cryptographic evidence. For France Identité on `verified`: contains the OIDC ID token vault reference. Empty on failure paths or Personalausweis.
`sessionBinding`	object \| null	Session and subject identifiers from the eID protocol. Contains `protocol` (the wire protocol used, e.g. `"oidc"`, `"oauth2"`, `"proprietary"`), `subjectId`, `sessionId`, and `transactionId`. Any of the identifier fields may be `null` if not provided by the protocol. `null` on failure paths.
`issues`	array	Method-level issues encountered during the eID authentication. Each entry has `code` (string), `severity` (`"error"` or `"warning"`), and `message` (string \| null). Empty on the `verified` route and on cancellation paths. On `not_verified`: contains `{ code: "insufficient_assurance_level", severity: "error" }` when the eID provider authenticated the user but at a lower assurance level than requested; contains technical failure codes (e.g. `cardBlocked`) for Personalausweis card errors.

Example payloads

BasicIdentity — verified

{
  "dataBlockId": "01940000-0000-7000-8000-000000000001",
  "type": "BasicIdentity",
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "dataBlockId": "01940000-0000-7000-8000-000000000002",
  "type": "ExtendedIdentity",
  "portrait": { "$ref": "vault", "$id": "020ff369-43d8-4b8a-94e7-6814c0bdc35a" },
  "nationality": "FRA",
  "personalAdministrativeNumber": null,
  "familyNameBirth": "Dupont",
  "givenNameBirth": "Jean",
  "sex": 1,
  "emailAddress": null,
  "mobilePhoneNumber": null,
  "residentAddress": "24 RUE DANTON 35700 RENNES FRANCE",
  "residentStreet": "RUE DANTON",
  "residentHouseNumber": "24",
  "residentHouseName": null,
  "residentCountry": "FR",
  "residentState": "Bretagne",
  "residentCity": "RENNES",
  "residentPostalCode": "35700"
}

Verification — verified

{
  "dataBlockId": "01940000-0000-7000-8000-000000000003",
  "type": "Verification",
  "status": "verified",
  "provider": null,
  "trustFramework": "eidas",
  "assuranceLevel": "substantial",
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "txn-abc123",
  "terminationReason": null,
  "methods": [
    {
      "type": "eid",
      "schemeId": "franceIdentite",
      "authority": "Agence Nationale des Titres Sécurisés",
      "countryCode": "FR",
      "evidence": [{ "$ref": "vault", "$id": "7fa3c821-91be-4a0d-b2d1-0e5f3c9d1234" }],
      "sessionBinding": {
        "protocol": "oidc",
        "subjectId": "FR-sub-9f8e7d6c5b4a",
        "sessionId": "sess-1a2b3c4d5e6f",
        "transactionId": null
      }
    }
  ]
}

Verification — not_verified (provider rejected)

{
  "dataBlockId": "01940000-0000-7000-8000-000000000004",
  "type": "Verification",
  "status": "rejected",
  "provider": null,
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:03:45.000Z",
  "verificationProcessId": "txn-def456",
  "terminationReason": null,
  "methods": [
    {
      "type": "eid",
      "schemeId": "franceIdentite",
      "authority": "Agence Nationale des Titres Sécurisés",
      "countryCode": "FR",
      "evidence": [],
      "sessionBinding": null,
      "issues": []
    }
  ]
}

Verification — not_verified (insufficient assurance level)

Defensive case — should not occur under normal circumstances. France Identité authenticated the user successfully, but the assurance level returned by the provider (low) was lower than the one requested (substantial). This is a last-resort guard: the requested level is passed to the provider during the OIDC flow, so a mismatch indicates unexpected provider behaviour. trustFramework and assuranceLevel are null because the requested level was not confirmed. The session binding and OIDC evidence are present because authentication did complete at the provider. methods[0].issues contains the insufficient_assurance_level diagnostic.

{
  "dataBlockId": "01940000-0000-7000-8000-000000000005",
  "type": "Verification",
  "status": "rejected",
  "provider": null,
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:05:22.000Z",
  "verificationProcessId": "txn-ghi789",
  "terminationReason": null,
  "methods": [
    {
      "type": "eid",
      "schemeId": "franceIdentite",
      "authority": "Agence Nationale des Titres Sécurisés",
      "countryCode": "FR",
      "evidence": [{ "$ref": "vault", "$id": "3bc9d145-2a7f-4e1c-8f6b-9e0d12345678" }],
      "sessionBinding": {
        "protocol": "oidc",
        "subjectId": "FR-sub-1a2b3c4d5e6f",
        "sessionId": "sess-9g8h7i6j5k4l",
        "transactionId": null
      },
      "issues": [
        {
          "code": "insufficient_assurance_level",
          "severity": "error",
          "message": "Requested assurance level \"substantial\" for trust framework \"eidas\" was not met: France Identité returned assurance level \"low\" for trust framework \"eidas\"."
        }
      ]
    }
  ]
}

Authenticates users using a national electronic identity document​

Key features​

Method selection modes​

Configuration​

Example​

Input data blocks​

Routes​

Output data blocks​

Verification data block​

methods[].eid​

Example payloads​