Recommended integration

Hosted UnifyID

Use the OAuth 2.0 authorization code flow with PKCE to redirect people through a UnifyID-managed experience for account authentication, face assurance, consent, and recovery.

https://api.dev.unifyid.io/v1/oauth/authorize?response_type=code&client_id={clientId}&redirect_uri={registeredRedirectUri}&scope=openid%20profile&state={state}&nonce={nonce}&code_challenge={codeChallenge}&code_challenge_method=S256

Authorization endpoint

GET/v1/oauth/authorize

Starts the hosted flow. Request values are validated before the person signs in, and consent is bound to the application, purpose, scopes, and identity.

Parameter	Required	Description
`response_type`	Yes	Must be code.
`client_id`	Yes	The active application Client ID.
`redirect_uri`	Yes	Must exactly equal a registered redirect URI.
`scope`	Yes	Space-separated scopes enabled for the application.
`state`	Yes	Unpredictable value bound to the initiating session.
`nonce`	With openid	One-time value that must match the ID token.
`code_challenge`	Public clients	Base64url SHA-256 digest of the PKCE verifier.
`code_challenge_method`	With PKCE	Must be S256.
`purpose`	Recommended	Plain-language reason shown to the person.

Callback outcomes

// Approved
https://your-app.example/callback?code={one_time_code}&state={state}

// Denied or failed
https://your-app.example/callback?error=access_denied&state={state}

Your callback must handle approval, denial, expiration, malformed requests, and the person closing the flow. Do not create an application session until state and tokens have been validated.

Popup-first desktop experience

On desktop, open a centered authorization window directly from the person's click. Keep the original application in place, complete the exchange through the callback's same-origin backend, send only a completion signal to the opener, and close automatically. Use full-page redirect on mobile and whenever popup use is unavailable.

const result = await UnifyID.authorize({
  clientId: "vid_sandbox_...",
  redirectUri: "https://your-app.example/auth/callback",
  scopes: ["openid", "profile", "email", "identity_verified"],
  purpose: "Create and secure your account",
  authorizeUrl: "https://api.dev.unifyid.io/v1/oauth/authorize",
  mode: "popup"
});

if (result.completed) {
  window.location.assign("/dashboard");
}

Token endpoint

POST/v1/oauth/token

Exchange the code from a trusted backend, or from a public client using the original PKCE verifier. Codes cannot be replayed.

{
  "grant_type": "authorization_code",
  "code": "{one_time_code}",
  "redirect_uri": "https://your-app.example/callback",
  "client_id": "vid_sandbox_...",
  "code_verifier": "{original_verifier}",
  "client_secret": "{confidential_clients_only}"
}

Required validation

1Validate state before code exchange
2Use the original redirect URI and PKCE verifier
3Validate ID token signature and approved algorithm
4Validate issuer, audience, expiry, nonce, and token type
5Use pairwise sub as the account key
6Discard the transaction after one attempt

The hosted page, rather than your application, handles UnifyID passwords, MFA, live selfie capture, face matching, consent, and account recovery.

Retrieve approved information

Call GET /v1/userinfo with the issued access token. Use document endpoints only when identity_documents and the relevant document fields were approved.