Skip to main content
Didit’s identity verification bridge is an OpenID Connect authorization server that runs a Didit verification whenever your identity platform asks for one, and returns the verified identity in a signed ID token. It speaks two profiles: the delegated identity verification contract of Okta’s “bring your own identity verification vendor” (BYO IDV) framework, also used from Auth0, and standard OpenID Connect for any relying party or identity broker, such as Keycloak.

Choose a profile

Didit enables one profile for each client, when it enables the integration.

Endpoints

Every endpoint lives under the identity verification bridge base URL. Production and sandbox use the same endpoints. The application associated with your client credentials determines the environment. Use separate client credentials and a workflow belonging to the corresponding application for each environment. See Sandbox & Test Data for simulated verification outcomes. The discovery document at {base}/.well-known/openid-configuration advertises all of them: Client authentication uses client_secret_basic or client_secret_post. The redirect_uri of every request must be exactly one of the redirect URIs Didit registered for your client: a trailing slash, an extra path segment or a query string makes it a different URI. ID tokens are signed with RS256; verify them against the JWKS endpoint. The access token returned with the ID token is valid for one hour and is accepted only by the UserInfo endpoint, in the Authorization: Bearer header or the access_token form field of a POST.

Client credentials

Didit issues a dedicated client secret for the integration when it enables it, and shows it once. Store it in your identity platform’s secret store: it authenticates your client at the PAR and token endpoints and has no other use. The UserInfo endpoint takes the access token instead. The application’s API keys are not accepted as the client secret of an integration that has its own secret. Didit can rotate the secret on request. The replaced secret keeps working for a grace period (24 hours unless you ask for another one), so you can switch without downtime.
Integrations set up before dedicated secrets existed authenticate with the application’s Primary API key. They keep working until Didit issues them a dedicated secret; from then on only the new secret is accepted.

Flow

  1. The relying party pushes the authorization request to POST /par, including the PKCE challenge, state, nonce, its registered redirect_uri, the scopes openid profile identity_assurance, and the claims it wants verified. Didit returns a single-use request_uri that is valid for 60 seconds.
  2. The relying party redirects the user’s browser to GET /authorize?request_uri=.... Didit creates a verification session and sends the user into the hosted verification flow.
  3. When the user finishes, Didit evaluates the verification decision, compares the extracted identity against the claims that were pushed, and returns the user to the relying party’s redirect_uri with a one-time code and the original state.
  4. The relying party exchanges the code at POST /token with its code_verifier and receives a signed ID token.
With the OpenID Connect profile, step 1 is optional: your broker can send the same parameters straight to GET /authorize, with its client_id, as a plain authorization request. It then repeats the redirect_uri at POST /token. The user has 15 minutes from the authorization request to finish the verification. The authorization code is valid for 5 minutes and can be used once.

Requesting claims

Send the claims to compare inside the standard OpenID Connect claims parameter of the PAR request. Both given_name and family_name are supported, and both are always compared fuzzily. verified_claims is an array, matching Okta’s BYO IDV profile and the ID token response below.
With the OpenID Connect profile you can also name the claims directly, as in OpenID Connect Core section 5.5: {"id_token": {"given_name": {"value": "Lucas"}}}. A verified identity that does not match a requested value ends the request with error=access_denied.

The ID token

This section describes the Okta and Auth0 profile; the OpenID Connect profile is described below. The ID token carries a verified_claims array. assurance_level is VERIFIED only when the verification session was approved and every requested claim matched the verified document. Otherwise it is FAILED. Didit reads the session again when the code is redeemed, so a session declined after the user came back (for example after a fraud review) is FAILED too.
verification_process is the Didit session id, so you can look the verification up in the console or through the sessions API.
Treat the user as verified only when trust_framework is IDV-DELEGATED and assurance_level is VERIFIED. Any other combination means the verification did not succeed.
Okta’s protocol has only two outcomes, so a session that ends in manual review (In Review, Resubmitted or Awaiting User) is returned as FAILED. Didit can instead keep the user on a “Your verification is being reviewed” page for a set time: if a reviewer approves within it, the user continues with VERIFIED; otherwise the result is FAILED.

OpenID Connect profile

With the OpenID Connect profile the ID token and the UserInfo response carry standard claims at the top level, so any identity broker can map them without custom code.

Scopes and claims

Identity claims are released only when the session is approved. Scopes the bridge does not support are ignored, and the token response lists only the granted ones. A claim the verified document does not carry is left out rather than sent empty. Dates use YYYY-MM-DD, nationality and document.issuing_country use ISO 3166-1 alpha-3 codes, address.country uses ISO 3166-1 alpha-2, and gender is female or male (left out otherwise).
The UserInfo endpoint returns the same claims for the access token issued with the ID token. Didit does not keep a copy of them for the integration: the token and UserInfo endpoints read them from the verification session when your platform asks, so deleting the session removes them from both.

Outcomes

What your redirect URI receives depends on the session status when the user comes back from the verification: A user who has not finished within 15 minutes, and a verified identity that does not match a requested claim value, also end with error=access_denied. Treat a user as verified only when verification_status is Approved.

Manual review

A session that ends in manual review is never reported as a failure. Your broker receives a pending result right away, or, if you ask Didit for a review wait, after the user has waited on a “Your verification is being reviewed” page for up to that time; a reviewer who decides within it sends the user on with the final result. To learn the final decision of a pending result, use verification_session_id: subscribe to webhooks or read the session decision with the sessions API. While its access token is valid, the UserInfo endpoint also returns the identity claims as soon as a reviewer approves the session.

The subject (sub)

By default sub is the verification session id, so it is new for every verification. Didit can instead give your client a document subject: an opaque identifier derived from the issuing country and the document number. It is the same every time the same document is verified for your client, different for every client, and cannot be turned back into the document number. A new or different document gives a new value. Use it when your broker links the verified person to an existing account across verifications.

Configure Okta

Ask Didit to enable identity verification for your production and sandbox applications, associate each with its verification workflow, and register the exact callback URL for each Okta tenant. An existing application or API key alone does not enable this integration. In the Okta Admin Console, add a custom identity verification vendor and fill in the values below. Okta creates the integration as an identity provider of type IDV_STANDARD with protocol ID_PROOFING, and you then reference it from an Account Management Policy rule. Configure production and sandbox as separate identity verification integrations with their respective credentials. Use the endpoints above for both. The client secret is required even though the flow also uses PKCE. Give Didit your callback URL so it can be registered on your client. Okta builds it as {yourOktaOrgUrl}/idp/identity-verification/callback.

Configure Keycloak

Keycloak brokers Didit as an OpenID Connect identity provider, with no custom code. These steps were tested end to end with Keycloak 26.
  1. Ask Didit to enable the OpenID Connect profile for your application and to register your broker’s redirect URI: https://{your-keycloak-host}/realms/{realm}/broker/{alias}/endpoint, where {alias} is the identity provider alias you choose below. Didit gives you the client ID and the client secret.
  2. In the Keycloak admin console, open your realm, go to Identity providers and add an OpenID Connect v1.0 provider with the alias you registered.
  3. Set Discovery endpoint to https://apx.didit.me/auth/idv/.well-known/openid-configuration. Keycloak fills in the authorization, token, UserInfo, issuer and JWKS URLs from it.
  4. Set Client authentication to Client secret sent as basic auth, and enter the Client ID and Client Secret.
  5. Turn on Use PKCE with the S256 method, and keep Validate signatures and Use JWKS URL on.
  6. Set Scopes to the scopes whose claims you need, for example openid profile document address.
  7. Add an Attribute Importer mapper for every claim you want on the Keycloak user. Keycloak reads a nested claim with a dot: map document.number to a document_number attribute, address.locality to address_locality, and so on. Keycloak maps given_name, family_name and email to the user’s first name, last name and email itself.
Since Keycloak 24 the realm user profile discards attributes it does not declare. Declare the attributes your mappers write, or turn on unmanaged attributes, in Realm settings > User profile. A pending result carries no identity claims, so a realm that requires first name, last name or email shows Keycloak’s profile review form for it.
Check verification_status before you trust the identity, for example in a post-login flow or in your application: it is Approved only for a verified identity. Use Sync mode Force if every verification should refresh the imported attributes.

Configure Auth0

Auth0 has no native IDV vendor slot, so verification runs from a post-login Action that redirects the user into the same flow, with the Okta and Auth0 profile. Store DIDIT_IDV_BASE, DIDIT_CLIENT_ID and DIDIT_CLIENT_SECRET (the client secret Didit issued for the integration) as Action secrets, and register https://{yourAuth0Domain}/continue as the redirect URI with Didit.
Auth0 appends its own state to the /authorize redirect so it can resume the login. Didit adopts that state and echoes it back to /continue, which is what lets Auth0 complete the transaction - you don’t thread Auth0’s state through the PAR body (it isn’t generated until the redirect).
Store the PKCE code_verifier per login transaction (keyed by event.transaction.id), not in a single app_metadata field. If a user retries or runs an overlapping login, a single shared field gets overwritten and the token exchange fails with invalid_grant.

Errors

Errors follow RFC 6749, RFC 6750 and RFC 9126. Until Didit has validated the redirect_uri, errors are returned to the caller as JSON; after that, they are sent to the redirect_uri with the original state. Authorization codes, request_uri values, and verification sessions are all single use.
Last modified on November 18, 2026