Trust Journeys API

Server-side orchestration

Journey endpoints require the private site or mobile-application secret. Do not call them directly from browser JavaScript. Your backend supplies the authenticated subject and protected operation context.

Start a web journey

POST https://api.vettiguard.com/v1/journeys/start
Content-Type: application/json

{
  "secret": "YOUR_PRIVATE_SITE_SECRET",
  "journey_key": "transaction-approval",
  "subject_id": "customer-4821",
  "action": "approve-transfer",
  "operation_reference": "TRANSFER-12345",
  "risk_level": "high",
  "risk_score": 0.92,
  "consent_version": "2026-08",
  "request_reference": "REQ-9F2A"
}

The response contains a short-lived session_token, the selected verification method, the method endpoint, and the evidence required by the journey.

{
  "success": true,
  "journey": {
    "key": "transaction-approval",
    "name": "Transaction approval"
  },
  "session_token": "vg_journey_...",
  "expires_in": 300,
  "method": "facial_authorization",
  "requested_assurance": "high",
  "policy_version": 4,
  "consent": {
    "required": true,
    "version": "2026-08"
  },
  "endpoint": "https://api.vettiguard.com/v1/facial/authorization/intent",
  "requirements": {
    "identity": true,
    "liveness": false,
    "authorization": true,
    "operation_binding": true
  }
}

Execute the returned method

Use the normal VettiGuard web or native client for the returned method. The journey session does not replace the facial, challenge, or device proof; it binds that proof to the configured business policy.

• human_verification — browser challenge flow
• facial_liveness — live-person check
• facial_enrollment — create or replace an identity enrollment
• facial_authorization — match a live user to an enrollment
• device_authorization — native biometric prompt and signed operation

Verify the journey and proof together

POST https://api.vettiguard.com/v1/journeys/siteverify
Content-Type: application/json

{
  "secret": "YOUR_PRIVATE_SITE_SECRET",
  "session_token": "vg_journey_...",
  "response": "vg_response_...",
  "subject_id": "customer-4821",
  "action": "approve-transfer",
  "operation_reference": "TRANSFER-12345",
  "consent_version": "2026-08",
  "consent_accepted": true
}

Continue the protected operation only when success is true and the journey status is completed.

{
  "success": true,
  "trust": {
    "method": "facial_identity_authorization",
    "assurance_level": "high",
    "identity_bound": true,
    "liveness_verified": true,
    "operation_bound": true,
    "authorization_capable": true
  },
  "journey": {
    "key": "transaction-approval",
    "status": "completed"
  },
  "error-codes": []
}

A failed attempt may include a policy-approved next_step. The application must obtain a fresh response proof before retrying. Identity-bound journeys must repeat the same server-derived subject_id during final verification.

Read status or request assisted review

Applications can check a session without consuming it, or request an assisted-review case when the configured user journey cannot be completed. Review does not convert a failed proof into approval.

POST https://api.vettiguard.com/v1/journeys/status
Content-Type: application/json

{
  "secret": "YOUR_PRIVATE_SITE_SECRET",
  "session_token": "vg_journey_..."
}

POST https://api.vettiguard.com/v1/journeys/escalate
Content-Type: application/json

{
  "secret": "YOUR_PRIVATE_SITE_SECRET",
  "session_token": "vg_journey_...",
  "reason_code": "accessibility-alternative-required",
  "priority": "normal",
  "operation_label": "Transfer ending 1234"
}

The escalation response contains a privacy-safe case reference. Your application remains responsible for any OTP, support, documentary, or manual-decision process used outside the VettiGuard proof.

Android and iOS endpoints

POST /v1/mobile/journeys/start
Authorization: Bearer YOUR_MOBILE_SERVER_SECRET

POST /v1/mobile/journeys/siteverify
Authorization: Bearer YOUR_MOBILE_SERVER_SECRET

POST /v1/mobile/journeys/status
Authorization: Bearer YOUR_MOBILE_SERVER_SECRET

POST /v1/mobile/journeys/escalate
Authorization: Bearer YOUR_MOBILE_SERVER_SECRET

Mobile requests must also include the registered platform and application identifier required by the existing mobile verification API.

Keep the application backend authoritative

• Derive subject_id, amount, beneficiary, recovery target, and operation reference from server-side records.
• Never expose the private site or mobile secret to a browser or native application.
• Treat journey and response tokens as short-lived, single-use credentials.
• Validate the action and operation reference again before committing the business operation.
• Do not treat a fallback method as equivalent unless the configured journey explicitly allows it.
• Record the consent version and a non-sensitive request reference when evidence is required.
• Keep assisted review separate from cryptographic or biometric approval; operators cannot override failed proof.
• Use policy approval and version history for material changes to high-consequence journeys.