Getting started with Truora Pass

What is Truora Pass?

Truora Pass is an OAuth 2.0 / OpenID Connect Identity Provider. Users verify their identity once inside Truora Pass — document and face verification — and can then sign in to any integrated application and share their verified identity data with explicit consent, without repeating the process. Your application never runs the verification itself: Truora Pass is the verifier, and your application reads the results.

You integrate it the way you would integrate any identity provider (Google, Okta, Auth0): add a sign-in button, send the user to Truora Pass via a redirect or modal, receive an authorization code, and exchange it server-side for tokens. What you get on top of authentication:

• Faster onboarding, higher conversion — users who already verified with Truora Pass sign up for your application without re-uploading documents or repeating face capture.
• Identity verification resolved — regulatory document and face verification happens inside Truora Pass; your application consumes the result as claims.
• Identity reuse across your products — one verified identity works in every application you integrate.

How it works

Every integration follows the same OAuth 2.0 / OIDC shape:

1. Your application sends the user to Truora Pass — via a browser redirect, an embedded modal, or a push to the user’s own device.
2. The user authenticates in Truora Pass and consents to the scopes your application requested.
3. Truora Pass hands your application a single-use authorization code (or, for the decoupled flow, an auth_req_id you poll with).
4. Your server exchanges the code for tokens at POST /v1/oauth2/token and receives an access_token, a refresh_token, and — when the openid scope was granted — an id_token.
5. Your server calls GET /v1/oauth2/userinfo with the access token to read the user’s verified identity claims.

Note: Treat the access token and ID token as opaque strings. All identity claims are released through the UserInfo endpoint — call it from your server instead of decoding tokens.

Choose an integration flow

All three flows end the same way: a server-side token exchange at POST /v1/oauth2/token followed by GET /v1/oauth2/userinfo.

Hosts

All API endpoints are versioned under /v1/oauth2/... on the API host.

Note: You can try the full redirect flow yourself with the CapiBank demo application at https://demo.pass.truora.com — the worked example in the Authorization Code flow guide mirrors it.

Before you start

You need a registered application. Registration is self-serve on the Truora Pass Dashboard (https://dashboard.pass.truora.com): sign in at https://account.truora.com, open the dashboard, and create the application yourself. That gives you:

• A client_id (prefixed WLT_APP_) and a client_secret — the secret is shown exactly once, so store it securely.
• Your registered redirect_uris and allowed scopes, which you can edit later from the dashboard.

See Registering your application for the step-by-step walkthrough and the full field reference.

Integrate with an AI coding agent

If you build with an AI coding assistant, paste the prompt below to have it scaffold the canonical redirect integration. The full list of these guides is also published in a machine-readable index at https://developer.truora.com/llms.txt — your agent can fetch it to read the complete documentation.

Implement "Sign in with Truora Pass" (OAuth 2.0 Authorization Code flow) in this
application. Truora Pass is an OAuth 2.0 / OpenID Connect Identity Provider.
The hosts are: IdP host https://pass.truora.com and API host
https://api.pass.truora.com.

1. Build the authorize URL on the IdP host and redirect the user's browser to it:
   https://pass.truora.com/authorize with query parameters client_id,
   redirect_uri (must exactly match a registered URI), response_type=code,
   scope (space-delimited, e.g. "openid profile email"), and a fresh unguessable
   state value bound to the user's session.
2. Handle the callback at redirect_uri: verify that state matches, then read the
   single-use code query parameter (on failure the callback carries error and
   error_description instead of code).
3. Exchange the code server-to-server (never in the browser — this request
   carries the client_secret): POST https://api.pass.truora.com/v1/oauth2/token
   with Content-Type: application/json and JSON body {"grant_type":
   "authorization_code", "code": "...", "client_id": "...", "client_secret":
   "...", "redirect_uri": "..."}. The response contains access_token, token_type,
   expires_in, scope, refresh_token, and id_token (when the openid scope was
   granted).
4. Read the user's identity: GET https://api.pass.truora.com/v1/oauth2/userinfo
   with the header Authorization: Bearer <access_token>. Treat the tokens as
   opaque strings — all identity claims come from this endpoint.
5. Store the refresh_token securely server-side. Refresh tokens rotate on every
   use: POST /v1/oauth2/token with JSON body {"grant_type": "refresh_token", ...}
   returns a new refresh_token — always persist the newest one.
6. Handle token-endpoint errors: HTTP 401 (bad client credentials) and HTTP 400
   (invalid or expired code, redirect_uri mismatch, reused refresh token) —
   restart the authorization flow when a grant is no longer redeemable.

Full documentation index (fetchable): https://developer.truora.com/llms.txt

All guides

• Registering your application — obtain credentials and configure your app.
• Authorization Code flow — the canonical redirect integration, end to end.
• Embedded SDK — the TruoraPass modal flow with response_mode=web_message.
• CIBA flow — decoupled, backchannel authentication.
• Refresh tokens — token rotation and long-lived sessions.
• UserInfo and claims — reading identity data with the access token.
• Scopes reference — every scope and the claims it grants.
• Consuming verification results — reading identity-verification status and trust level.
• Errors and troubleshooting — error responses and common mistakes.