Back to evaluation kit Section 11
Integration options

Connect Incode to your existing stack

These are custom integration options for teams building directly against Incode's APIs. If you're using Okta, Microsoft Entra, PingIdentity, or another major IdP, we have out-of-the-box integrations available — browse the full integration library in our developer docs.

Option 01 · Recommended

OpenID Connect (OIDC)

Incode acts as an Identity Provider (IDP) — your application is the Relying Party (RP). Users verify their identity biometrically through Incode, and your app receives signed JWT tokens containing verified identity claims. If you're already on Okta, Entra, or PingIdentity, Incode plugs in as a trusted IDP with minimal engineering lift.

Authorization code flow
User
Employee / Candidate
Your App (RP)
Relying Party
Incode (IDP)
Identity Provider
Access application redirect → /oauth2/authorize Prompted for Identity Verification redirect → callback?code=AUTH_CODE Completed Identity Verification POST /oauth2/token (server-side) id_token + access_token GET /userinfo (Bearer access_token) user attributes (email, verified status, scores) Browser redirect Server-to-server Token / attributes
Step-by-step integration guide
1
Create an OIDC integration in your Workforce dashboard
Navigate to Integrations → New Integration → OpenID Connect in your Incode Workforce dashboard. Give it a name, select your authentication method, and Incode will generate your client_id and client_secret. You'll also configure your redirect_uri values here — these must match exactly what you send in the authorization request.
ℹ Three auth methods are supported: Client Secret Post, Client Secret Basic, and Client Secret JWT. Create a separate OIDC integration for each auth method you need.
2
Copy your endpoints
After creating the integration, your Workforce dashboard will display the endpoint URLs for your instance. Use these to configure your relying party. The well-known discovery document returns all endpoints automatically.
SandboxProduction
Production discovery document
GET https://auth.incode.com/.well-known/openid-configuration
Sandbox discovery document
GET https://auth.demo.incode.com/.well-known/openid-configuration
GET{issuer}/oauth2/authorizeAuthorization endpoint
POST{issuer}/oauth2/tokenToken endpoint
GET{issuer}/oauth2/jwksPublic keys for JWT verification
GET{issuer}/userinfoUser attributes
GET{issuer}/connect/logoutEnd session
3
Specify your redirect URIs
In the integration dashboard, add all redirect URIs your application will use. These are the URLs Incode will return the authorization code to after the user completes verification. The redirect_uri in each authorization request must exactly match one of these registered values — unrecognized URIs will result in an error.
4
Redirect the user to the authorization endpoint
When a user needs to verify their identity, redirect them to Incode's authorization endpoint. They'll complete the biometric verification flow — document capture, liveness check, face match — and be redirected back to your app with an authorization code.
Authorization request
https://auth.demo.incode.com/oauth2/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.com/callback &response_type=code &scope=openid%20profile%20email &state=RANDOM_CSRF_TOKEN &login_hint=user@company.com // optional — for identity matching
ParameterDescriptionRequired
client_idClient identifier from your Workforce dashboard integrationRequired
redirect_uriMust exactly match a URI registered in your integration configRequired
response_typeMust be codeRequired
scopeMust include openid. Add profile and email for user claims in the ID token. Other supported scopes: phone, address, groups, rolesRequired
stateCSRF protection token — returned unchanged to your redirect URI. Always validate this on callbackRecommended
login_hintPass a known email or user identifier to pre-fill identity context and enable matching against an existing employee record. Particularly useful for re-verification and step-up authentication flows where you already know who the user should beOptional
5
Receive the authorization code
After the user completes verification, Incode redirects to your redirect_uri with a short-lived authorization code. Validate the state parameter before proceeding.
Callback
https://yourapp.com/callback ?code=AUTH_CODE &state=RANDOM_CSRF_TOKEN
6
Exchange the code for tokens (server-side)
Send a server-side POST to the token endpoint to exchange the authorization code for an id_token and access_token. This must happen server-to-server — never expose your client_secret in client-side code.
Token exchange (Client Secret Post)
POST https://auth.demo.incode.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTH_CODE &redirect_uri=https://yourapp.com/callback &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET
Token response
{ "access_token": "eyJhbGciOiJSUzI1NiJ9...", "id_token": "eyJhbGciOiJSUzI1NiJ9...", "token_type": "Bearer", "expires_in": 1800 }
🔒 Never expose client_secret in frontend code. Token exchange must happen on your server. Rotate your client secret periodically via the Workforce dashboard.
7
Validate and decode the ID token
The id_token is a signed JWT. Verify its signature using the public key from the JWKS endpoint, then check the iss, aud, and exp claims. The decoded payload contains the verified identity claims for the user.
Decoded ID token payload (scope: openid profile email)
{ "sub": "69eb79007bf0a36b5cb3a2d8", // Incode subject ID "identity_id": "69e0ef4ea7da4d0a67d5267f", // Incode identity record ID "interview_id": "69eb79007bf0a36b5cb3a2d8", // verification session ID "iss": "https://auth.demo.incode.com", "aud": "YOUR_CLIENT_ID", "preferred_username": "user@company.com", "email": "user@company.com", "auth_overall_status": "OK", // OK | FAIL | MANUAL_REVIEW "auth_overall_score": 0.0, "exp": 1777041477, "iat": 1777039677, "jti": "574e3fc3-3f8b-4d93-8d27-98e36f6ba772" }
ClaimDescription
subUnique subject identifier for this user within Incode
identity_idIncode identity record — use this to fetch full verification results via the API
interview_idThe specific verification session ID for this authentication event
auth_overall_statusOK = verified  ·  FAIL = failed  ·  MANUAL_REVIEW = escalated for human review
auth_overall_scoreLiveness and biometric match confidence score
preferred_usernameReturned when profile scope is included
issauth.demo.incode.com (sandbox) · auth.incode.com (production)
ℹ Use the access_token to call GET /userinfo for additional user attributes beyond what's in the ID token.
8
Fetch richer user attributes from the userinfo endpoint
The ID token contains core identity claims. For a fuller profile — including name, birthdate, gender, and locale — call the /userinfo endpoint using the access_token as a Bearer token. This is a standard OIDC endpoint and returns attributes based on the scopes granted.
Userinfo request
GET https://auth.demo.incode.com/userinfo Authorization: Bearer ACCESS_TOKEN
Userinfo response (scope: openid profile email)
{ "sub": "69eb89c8212a375de8acb0fc", "identity_id": "69e0ef4ea7da4d0a67d5267f", "interview_id": "69eb89c8212a375de8acb0fc", "name": "JANE A. SMITH", "given_name": "JANE A. SMITH", "preferred_username": "jane.smith@company.com", "email": "jane.smith@company.com", "birthdate": "1985-06-15", "gender": "F", "locale": "en-US", "updated_at": 1777043931454 }
ClaimDescriptionScope required
subUnique Incode subject IDopenid
nameFull legal name as extracted from the verified documentprofile
given_nameGiven name from the verified documentprofile
birthdateDate of birth in YYYY-MM-DD format, extracted from documentprofile
genderGender as recorded on the documentprofile
localeUser's localeprofile
emailEmail address (from login_hint or user input)email
identity_idIncode identity record — use to fetch full verification results via APIopenid
interview_idThe specific verification session IDopenid
ℹ The name, birthdate, and gender fields are extracted directly from the verified government-issued document — not self-reported. This makes them significantly more reliable than standard profile data.
Full OIDC integration guide Browse developer docs
Option 02 · Workforce

B2B API — Workforce Verification

Incode's B2B API lets you programmatically request identity verification for employees — triggering a biometric verification session and receiving the result via webhook or polling. Ideal for ITSM-triggered re-verification, privileged access escalation, and help desk flows where your system initiates the request rather than the user.

🏢
Use cases
  • IT-triggered re-verification on role change
  • Step-up auth for privileged access requests
  • Help desk-initiated identity confirmation
  • Offboarding and access revocation confirmation
  • Periodic re-verification for compliance
⚡
How it works
  • Your system calls the B2B API with employee details
  • Incode sends verification request to the employee
  • Employee completes biometric verification
  • Result delivered via webhook or polling
  • Your system grants, denies, or escalates
1
Get an access token (client credentials)
The B2B API uses the OAuth2 client credentials grant — a machine-to-machine flow where your server authenticates directly with Incode's token endpoint using your client_id and client_secret. No user interaction required.
Token request
POST https://auth.demo.incode.com/oauth2/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET &scope=openid
Token response
{ "access_token": "eyJhbGciOiJSUzI1NiJ9...", "token_type": "Bearer", "expires_in": 300 }
ℹ Use sandbox credentials with auth.demo.incode.com during your POC. Switch to auth.incode.com for production.
2
Request a new B2B onboarding session
Use the access token from Step 1 as a Bearer token to call the B2B onboarding endpoint. Incode creates a verification session and returns a URL you can deliver to the employee via email, Slack, or an ITSM ticket.
Request
POST https://auth.demo.incode.com/omni/b2b/onboarding/request-new Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Accept: application/json api-version: 1.0 x-api-key: YOUR_API_KEY { "loginHint": "email", "integrationReference": "YOUR_INTEGRATION_REFERENCE", "notification": { "type": "URL" }, "name": "" }
FieldDescriptionRequired
loginHintIdentity hint used to match the employee — typically "email"Required
integrationReferenceYour integration reference ID from the Workforce dashboardRequired
notification.type"URL" returns a verification link you deliver yourself. Other types may trigger direct notification deliveryRequired
nameOptional display name for the sessionOptional
Response
{ "token": "SESSION_TOKEN", "interviewId": "69eb79007bf0a36b5cb3a2d8", "interviewCode": "INTERVIEW_CODE", "url": "https://verify.incode.com/s/SESSION_TOKEN" }
ℹ The Postman test script automatically stores token, interviewId, and interviewCode as environment variables for use in subsequent requests.
POSThttps://auth.demo.incode.com/oauth2/tokenGet access token
POSThttps://auth.demo.incode.com/omni/b2b/onboarding/request-newCreate B2B session
View B2B API docs Download Postman collection Download Tines story
Option 03 · Candidate

Omni Start API — Candidate Verification

Incode's Omni Start API initiates candidate identity verification sessions directly from your ATS or onboarding workflow. Your system creates the session, delivers the link to the candidate, and receives the result via webhook when they complete verification.

👥
Use cases
  • New hire identity verification (I-9)
  • Candidate fraud screening
  • International hire document check
  • Background check identity confirmation
🔗
Integration pattern
  • ATS triggers API call on offer accepted
  • Candidate receives verification link
  • Completes IDV on mobile or desktop
  • Webhook delivers result to your system
Start a candidate verification session
POST https://workforce-api.incode.com/omni/start { "configurationId": "YOUR_FLOW_CONFIG_ID", "countryCode": "ALL", "language": "en-US", "externalId": "candidate-789", // your ATS candidate ID "redirectionUrl": "https://yourapp.com/onboarding/complete" }
Response
{ "token": "SESSION_TOKEN", "interviewId": "sess_01HXYZ...", "url": "https://verify.incode.com/s/SESSION_TOKEN" // send to candidate }
View Omni Start API reference