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
- The relying party pushes the authorization request to
POST /par, including the PKCE challenge,state,nonce, its registeredredirect_uri, the scopesopenid profile identity_assurance, and the claims it wants verified. Didit returns a single-userequest_urithat is valid for 60 seconds. - 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. - 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_uriwith a one-timecodeand the originalstate. - The relying party exchanges the code at
POST /tokenwith itscode_verifierand receives a signed ID token.
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 Connectclaims 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.
{"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 averified_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.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).
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, useverification_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 typeIDV_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.- 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. - 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.
- 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. - Set Client authentication to Client secret sent as basic auth, and enter the Client ID and Client Secret.
- Turn on Use PKCE with the
S256method, and keep Validate signatures and Use JWKS URL on. - Set Scopes to the scopes whose claims you need, for example
openid profile document address. - Add an Attribute Importer mapper for every claim you want on the Keycloak user.
Keycloak reads a nested claim with a dot: map
document.numberto adocument_numberattribute,address.localitytoaddress_locality, and so on. Keycloak mapsgiven_name,family_nameandemailto 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.
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. StoreDIDIT_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.