Developers

Start the ceremony from your application. Validate the result in your backend.

Add a hosted digital handshake beside your existing identity and risk stack. Sonavera handles consent, the guided browser session, sensor orchestration, evidence composition, and supported result delivery.

View a sample resultRequest pilot access

Your backend validates the integration output. Your application owns thresholds, review rules, retries, fallback paths, and the protected action.

Customer-owned integration boundary
1. Startbackend/BFF, public-client OIDC, or API request
2. Redirecthosted consent and guided ceremony
Sonavera-owned runtimeCollect and compose evidence
3. Validatetoken, API result, or webhook
4. Evaluatecustomer policy and action
BrowserNo app install
ProtocolsOIDC or API redirect
DeliveryTokens, API retrieval, webhooks
PolicyRemains in your application

Integration paths

Choose the supported shape that fits your stack.

Completed, evidence-bearing outputs use the same canonical evidence artifact, but authentication and delivery guarantees are specific to each protocol. Check ceremony lifecycle and requested-deliverable state before parsing or evaluating evidence.

01 / OIDC step-up

Use backend/BFF or public-client initiation

Authorization Code with S256 PKCE returns an ES256-signed ID token. A backend/BFF can start the flow, or a public-client SPA can start it and forward the token to its backend for validation.

  1. 1Backend/BFF: keep state, nonce, and code_verifier server-side, bound to the protected transaction, expected flow, and expected subject or action references.
  2. 2Public-client SPA: the browser may retain state and code_verifier, but the backend must issue or verify the action-binding nonce or challenge and pre-bind the expected flow and subject or action references.
  3. 3In the backend, validate the ES256 signature against JWKS plus iss, aud, exp, iat, nonce, expected flow, ACR, applicable AMR, and required Sonavera namespaced claims. Require the flow-specific signed subject or action claims—and the deletion-subject binding where applicable—to match backend-owned transaction state.
  4. 4Apply customer policy only after backend validation succeeds.
02 / API redirect

Keep result retrieval in your backend

Create a ceremony with tenant credentials, redirect the browser to Sonavera, and retrieve the authoritative result after the user returns. Eligible terminal results can also include a Sonavera-signed resultToken.

  1. 1Create the ceremony and bind the customer action.
  2. 2Send the browser to the hosted handoff URL.
  3. 3Treat return parameters as advisory and retrieve the result with backend-held credentials.
  4. 4Validate resultToken when your integration uses the signed token for offline verification.
03 / Signed webhooks

Receive terminal notifications

Optional handshake.result.v1 webhook deliveries use HMAC signatures and the same flow-discriminated result envelope.

  1. 1Configure an HTTPS destination and webhook secret.
  2. 2Before parsing, verify the signature over the exact raw body and enforce timestamp freshness.
  3. 3Atomically reserve the event ID in a durable store before acting so concurrent or restarted delivery cannot replay the event.
  4. 4Keep authenticated backend retrieval as the recovery path.

Sample result

Inspect the evidence before you integrate.

This example is derived from deterministic measurement inputs composed through the production evidence path. It is illustrative and explicitly unsigned, so it is useful for rendering and integration planning but is not ceremony proof.

Understand the evidence modelDiscuss an integration

This complete document is rendered directly from Sonavera’s generatedverify/partial fixture. Confirm the current contract package during a pilot before building a production integration.

Illustrative evidence exampleunsigned · verify/partial
{
  "example_schema": 1,
  "scenario": "partial",
  "illustrative": true,
  "signed": false,
  "artifact": {
    "schema": 1,
    "provider": "Sonavera",
    "schema_uri": "https://api.sonavera.ai/.well-known/sonavera-evidence-schema#v1",
    "flow": "verify",
    "profile": {
      "id": "evidence_verification",
      "version": 1,
      "uri": "https://api.sonavera.ai/.well-known/sonavera-evidence-profiles#evidence_verification/v1",
      "digest": "sha256:c2c56b598ffc3294fde24a5df4e67aa8684a8ce074311bd39cf5e91c1357042e"
    },
    "index_score": 80,
    "index_measurements_status": "measurements_partial",
    "evidence_axes": [
      {
        "id": "identity_match",
        "measurement_normalized": 76.25,
        "index_points_allocated": 40,
        "index_points_earned": 30.5,
        "checks": [
          {
            "id": "face.identity_match.v1",
            "contributes_to_index": true,
            "measurement_status": "measurement_partial",
            "measurement_reason": "samples_insufficient",
            "samples_target": 10,
            "samples_collected": 9,
            "measurement_normalized": 73.8,
            "index_points_allocated": 28,
            "index_points_earned": 20.66
          },
          {
            "id": "voice.identity_match.v1",
            "contributes_to_index": true,
            "measurement_status": "measurement_complete",
            "measurement_reason": null,
            "samples_target": 1,
            "samples_collected": 1,
            "measurement_normalized": 82,
            "index_points_allocated": 12,
            "index_points_earned": 9.84
          }
        ]
      },
      {
        "id": "face_continuity",
        "measurement_normalized": 82.73,
        "index_points_allocated": 15,
        "index_points_earned": 12.41,
        "checks": [
          {
            "id": "face.session_continuity.v1",
            "contributes_to_index": true,
            "measurement_status": "measurement_complete",
            "measurement_reason": null,
            "measurement_normalized": 82.72,
            "index_points_allocated": 15,
            "index_points_earned": 12.41,
            "details": {
              "algorithm_version": "anchorless_pairwise.v1",
              "observation_window_ms": 32000,
              "opportunities_scheduled": 32,
              "opportunities_evaluable": 31,
              "primary_face_observations": 30,
              "reliable_embeddings": 28,
              "temporal_bins_covered": 4,
              "longest_unobserved_gap_ms": 1500,
              "embedding_consistency_normalized": 88,
              "primary_face_observability_normalized": 80
            }
          }
        ]
      },
      {
        "id": "challenge_integrity",
        "measurement_normalized": 82,
        "index_points_allocated": 25,
        "index_points_earned": 20.5,
        "checks": [
          {
            "id": "phrase.challenge_response.v1",
            "contributes_to_index": true,
            "measurement_status": "measurement_complete",
            "measurement_reason": null,
            "measurement_normalized": 82,
            "index_points_allocated": 10,
            "index_points_earned": 8.2
          },
          {
            "id": "liveness.active_challenge.v1",
            "contributes_to_index": true,
            "measurement_status": "measurement_complete",
            "measurement_reason": null,
            "measurement_normalized": 82,
            "index_points_allocated": 15,
            "index_points_earned": 12.3
          }
        ]
      },
      {
        "id": "media_integrity",
        "measurement_normalized": 82,
        "index_points_allocated": 20,
        "index_points_earned": 16.4,
        "checks": [
          {
            "id": "pad.video_authenticity.v1",
            "contributes_to_index": true,
            "measurement_status": "measurement_complete",
            "measurement_reason": null,
            "measurement_normalized": 82,
            "index_points_allocated": 14,
            "index_points_earned": 11.48
          },
          {
            "id": "pad.voice_authenticity.v1",
            "contributes_to_index": true,
            "measurement_status": "measurement_complete",
            "measurement_reason": null,
            "measurement_normalized": 82,
            "index_points_allocated": 6,
            "index_points_earned": 4.92
          }
        ]
      }
    ],
    "supplemental_checks": [
      {
        "id": "browser.authenticity.v1",
        "contributes_to_index": false,
        "measurement_status": "measurement_complete",
        "measurement_reason": null,
        "measurement_normalized": null,
        "index_points_allocated": 0,
        "index_points_earned": 0
      },
      {
        "id": "network.authenticity.v1",
        "contributes_to_index": false,
        "measurement_status": "measurement_complete",
        "measurement_reason": null,
        "measurement_normalized": null,
        "index_points_allocated": 0,
        "index_points_earned": 0
      },
      {
        "id": "browser.continuity.v1",
        "contributes_to_index": false,
        "measurement_status": "measurement_complete",
        "measurement_reason": null,
        "measurement_normalized": null,
        "index_points_allocated": 0,
        "index_points_earned": 0
      },
      {
        "id": "network.continuity.v1",
        "contributes_to_index": false,
        "measurement_status": "measurement_complete",
        "measurement_reason": null,
        "measurement_normalized": null,
        "index_points_allocated": 0,
        "index_points_earned": 0
      }
    ]
  }
}

TypeScript SDK

Use a contract-compatible release, not an assumed latest tag.

The current SDK contract validates flow discrimination, evidence shape, profile digest, fixed-point arithmetic, measurement vocabulary, safe details, token claims, and webhook signatures. It does not contain your customer policy.

Release boundarypre-1.0 SDK
Confirm the compatible SDK version with Sonavera before integration.
Discuss SDK access

Browser prerequisites

Run preflight; do not assume universal coverage.

The hosted ceremony requires a supported modern browser, JavaScript, WebRTC, and permission to use a compatible camera and microphone. Browser, operating-system, embedded-webview, and device behavior can differ.

  • Check secure-context, camera, microphone, and WebRTC support before launch.
  • Use Sonavera’s preflight experience to surface permission and device problems.
  • Test the browser and device combinations that your own users rely on.
  • Offer a customer-owned fallback when the ceremony cannot collect required data.

Integration resources

Inspect what is available today.

EvidenceSample result

Inspect an illustrative, unsigned verification artifact and its measurement state.

IntegrationSupported paths

Compare OIDC, API redirect, signed result-token, and webhook delivery boundaries.

CompatibilityBrowser prerequisites

Review the runtime prerequisites and customer-owned fallback boundary.

ProductEvidence model

Understand ceremony state, the Evidence Index, checks, and flow-specific limits.

TrustSecurity and privacy

Review implemented controls, data boundaries, retention, and explicit non-claims.

Pilot accessHosted demo access

The hosted demo is currently limited to invited pilot participants. Request access for an evaluation.

Guided ceremony. Structured evidence. Customer-owned policy.

Use the in-page example to understand the result, then talk with us about the flow, compatible SDK release, and integration path for your sensitive action.

Request pilot accessReview the evidence model