Trust Check Lifecycle¶

Every Polyguard trust check follows three phases: Preparation, Trust Check, and Audit. This page describes what happens in each phase, how the JWT Bundle works, and how bilateral transparency is maintained.

Phase 1: Preparation¶

Preparation consists of the API calls needed to create a Link object before the trust check can begin.

Creating a Link¶

A Link defines the trust check configuration: its title, the required proofs, and any matching parameters. Links are reusable by default -- each use produces separate event logs and transaction affidavits.

POST /api/v1/links
{
  "title": "Identity Verification",
  "required_proofs": ["government_id", "location", "pg_presence"],
  "matching_params": { ... }
}

Optional: Import transaction-specific data

During preparation, you can optionally attach transaction-specific data (such as tokens or reference IDs) to the Link. This data can be passed between Polyguard environments via trust checks, enabling cross-system workflows.

What You Get Back¶

The API returns a Link object with an ID and a URL. The URL is what you embed in your web application (via the Web SDK) or pass to the mobile application (via the Mobile SDK) to initiate the trust check.

Phase 2: Trust Check¶

This is the real-time identity verification phase. The flow differs slightly between desktop and mobile contexts, but the underlying protocol is the same.

Desktop Flow¶

The Web SDK displays a modal overlay in the browser.
The End User scans a QR code with the Polyguard mobile app (or receives a push notification if already paired).
A WebSocket connection is established between the web application, the mobile app, and the Polyguard System -- all connected to the same regional endpoint.
The End User completes the required proofs on their mobile device (facial biometric, document scan, etc.).
Scores and presence results are processed within Polyguard infrastructure.
Results are returned to the web application via the SDK callback.

Mobile Flow¶

The Mobile SDK triggers a redirect into the Polyguard mobile app (or an in-app verification flow if using the embedded Mobile SDK).
The same WebSocket-based session coordination occurs.
On completion, the user is redirected back to the calling application with results.

WebSocket Session Coordination¶

Both the web and mobile sides of a trust check connect to the same Link Session via WebSockets. These connections must terminate at the same regional endpoint. The Polyguard System handles regional routing automatically (see Multitenancy & Regionalization for details on how redirects work).

Receiving Results¶

Trust check results are delivered to your application through two channels:

Channel	Delivery	Use Case
SDK callback	Synchronous, in the browser or mobile app	Immediate UX updates -- show verification status, unlock next step
Webhook	Asynchronous HTTP POST to your backend	Server-side validation, record-keeping, triggering downstream workflows

Webhook configuration

Webhooks are configured per App in the Polyguard object model. Set the webhook URL when creating or updating your App configuration. See the REST API docs for the webhook payload schema.

Phase 3: Audit¶

The audit phase is available at any time after a trust check completes. It provides full transparency into what was verified, by whom, and with what cryptographic backing.

Available Audit Data¶

Resource	Description	Access
Event Logs	Detailed record of every action taken during the trust check	REST API
Transaction Affidavits	Cryptographically signed, non-repudiable records of the completed trust check	REST API
Public Key Infrastructure	Well-known endpoints for locating PolyUser public keys and verifying JWT signatures	HTTPS (well-known URIs)

Bilateral Transparency¶

All audit logs are available to all parties to each trust check. This means:

The Platform Operator can access logs for compliance and dispute resolution.
The Business User can review verification outcomes for their transactions.
The End User can see what proofs were presented and to whom.

This bilateral transparency model ensures that no party holds an information advantage, and that the audit trail is available for independent verification by any participant.

JWT Bundle¶

The final step of every trust check is an HTTP POST of a signed JWT Bundle from the mobile app to the Polyguard System endpoint.

Structure¶

A JWT Bundle contains a set of individual JWTs, each signed by the relevant trust chain for the proof it represents. For example, a government ID proof JWT is signed with keys rooted in the identity verification partner's trust chain, while a device identity proof JWT is signed with keys rooted in Apple or Google's attestation infrastructure.

Key Fields¶

JWT Field	Value	Purpose
Issuer (`iss`)	Poly User ID	Identifies the End User. Allows any Relying Party to locate the relevant public keys at the Polyguard well-known location.
Audience (`aud`)	FQDN of the Polyguard System + App ID	Identifies the intended recipient and application context.

Verification¶

Any Relying Party can independently verify a JWT Bundle by:

Extracting the iss (Poly User ID) from each JWT.
Fetching the corresponding public key from the Polyguard well-known endpoint.
Validating the JWT signature against the public key.
Checking the aud field to confirm the JWT was intended for the expected application.

This makes trust check results independently verifiable without requiring a call back to Polyguard APIs.

Sequence Summary¶

Preparation         Trust Check                    Audit
-----------         -----------                    -----

Create Link    -->  Display modal / redirect  -->  Query event logs
(set proofs,        WebSocket session              Retrieve affidavits
 import data)       Biometric + proof capture      Verify JWT signatures
                    Score processing               (available to all parties)
                    JWT Bundle posted
                    Results via SDK + webhook

For implementation details, see the Web SDK Quick Start or the full Web SDK reference.