# 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](/truora-pass/userinfo_and_claims/) — call it from your server instead of decoding tokens.

## Choose an integration flow

| Flow | What it looks like | Guide |
|------|--------------------|-------|
| Authorization Code (redirect) | The user's browser is redirected to Truora Pass and back to your `redirect_uri`. The canonical web integration. | [Authorization Code flow](/truora-pass/authorization_code_flow/) |
| Embedded SDK (web_message) | Truora Pass opens in a modal on your own page via the `TruoraPass` `client.js` SDK; your page receives the code through a callback. | [Embedded SDK](/truora-pass/embedded_sdk/) |
| CIBA (decoupled) | Your backend starts the request; the user approves on their own device; your backend polls for tokens. No browser redirect at all. | [CIBA flow](/truora-pass/ciba_flow/) |
| Consent Gate (approvals) | Your backend asks a user to approve a rich prompt you compose (attachments, tables, a decision form); the decision is pushed back to your callback, with a checksum of the exact prompt shown. | [Approval requests](/truora-pass/approval_requests/) |

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

## Hosts

| Sign-in UI / SDK (IdP host) | API base | Dashboard |
|-----------------------------|----------|-----------|
| `https://pass.truora.com` | `https://api.pass.truora.com` | `https://dashboard.pass.truora.com` |

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](/truora-pass/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](/truora-pass/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.

```text
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](/truora-pass/registering_your_application/) — obtain credentials and configure your app.
- [Authorization Code flow](/truora-pass/authorization_code_flow/) — the canonical redirect integration, end to end.
- [Embedded SDK](/truora-pass/embedded_sdk/) — the `TruoraPass` modal flow with `response_mode=web_message`.
- [CIBA flow](/truora-pass/ciba_flow/) — decoupled, backchannel authentication.
- [Approval requests](/truora-pass/approval_requests/) — the Consent Gate: rich, human-in-the-loop approvals with attachments and a decision form.
- [Refresh tokens](/truora-pass/refresh_tokens/) — token rotation and long-lived sessions.
- [UserInfo and claims](/truora-pass/userinfo_and_claims/) — reading identity data with the access token.
- [Scopes reference](/truora-pass/scopes_reference/) — every scope and the claims it grants.
- [Consuming verification results](/truora-pass/verification_results/) — reading identity-verification status and trust level.
- [Verifiable credentials](/truora-pass/verifiable_credentials/) — SD-JWT credentials over the verified identity, selective disclosure, and revocation.
- [Verifying credential presentations](/truora-pass/verifying_presentations/) — requesting and verifying credential presentations from your backend.
- [Issuing and sharing credentials](/truora-pass/sharing_credentials/) — the end-user wallet flows: issue, share via link/QR, revoke.
- [Errors and troubleshooting](/truora-pass/errors_and_troubleshooting/) — error responses and common mistakes.