Hosted onboarding

Hosted onboarding is the recommended production baseline. Assayra owns responsive verification UI, camera guidance, consent, accessibility and workflow changes while your system owns customer authentication, session creation and final account decisions.

Before you start

You need:

• an Assayra tenant and administrator account;
• a published workflow ID;
• a Sandbox API key with applications:read, applications:write and workflows:read;
• a server route that can authenticate your customer; and
• an HTTPS webhook endpoint.

If you use the SDK, download and install the Web package first. A hosted redirect can also be implemented with the REST API and no frontend SDK.

Request flow

Customer browser         Your backend                 Assayra
      | POST /start            |                         |
      |----------------------->| POST /v1/applications   |
      |                        |------------------------>|
      |                        |<-- ID + applicant URL --|
      |<-- applicant URL ------|                         |
      | redirect or iframe ---------------------------->|
      |                        |<---- signed webhook ----|
      |                        | GET application -------->|

Step 1 — pin a workflow

In Client Admin Portal → Workflows, publish the workflow approved for this integration and copy its ID into server configuration. Do not dynamically select the newest workflow in production.

ASSAYRA_BASE_URL=https://your-assayra-origin.example
ASSAYRA_API_KEY=pl_sandbox_REPLACE_WITH_YOUR_SECRET
ASSAYRA_WORKFLOW_ID=wf_REPLACE_WITH_PUBLISHED_WORKFLOW

Step 2 — create the application on your server

Install the Web SDK and create an authenticated backend route as shown in Web SDK → Create an applicant session. The route must:

1. Confirm the signed-in customer is allowed to start verification.
2. Create the application with a unique idempotency key.
3. Persist the returned application ID against your customer.
4. Return only the application ID, invitation URL and expiry.

Never return the tenant API key or write the applicant URL to application logs.

Step 3 — choose delivery

Redirect

Call your start route and assign the returned URL to window.location. This is the simplest and most resilient option. See Hosted redirect for working frontend code.

Drop-in hosted

Pass the returned URL to mountAssayraHostedVerification. Give the container a stable height, configure frame-src and camera permissions, and call the returned cleanup function when the route unmounts. See Drop-in hosted.

Email or QR handoff

Set sendEmail: true to use the tenant’s configured email provider, or send the returned URL through your own secure channel. A QR code should contain the returned URL exactly and expire with the invitation. Do not place identity data in the URL or QR payload.

Step 4 — configure completion

Send the applicant to a neutral state such as Verification received. Do not display Approved based on a frontend event. The browser may close, lose connectivity or be manipulated.

Your backend completes the integration by:

1. Receiving application.submitted or application.decided.
2. Verifying the webhook signature against the raw body.
3. Rejecting stale timestamps and duplicate delivery IDs.
4. Calling GET /v1/applications/{id} with its API key.
5. Mapping the authenticated final state to your customer record idempotently.

Resume, resend and revoke

• Resume: reopen the same unexpired invitation URL. Assayra returns the current permitted step.
• Resend: call the invitation send operation when the recipient is unchanged.
• Regenerate: issue a replacement if the URL was exposed, sent to the wrong recipient or needs a different expiry. The previous token becomes unusable.
• Revoke: revoke when the verification is cancelled or the customer relationship ends.
• Expired: create/regenerate an invitation; never edit or extend an opaque token client-side.

Link scanners can consume invitation URLs before a person reaches them. Configure security tooling not to prefetch the verification path, or send customers to an authenticated page in your application that requests the invitation only after sign-in.

Production checklist

• Use a Live key and Live workflow only after activation.
• Restrict API key scopes and rotate on exposure.
• Allow only the exact Assayra origin in CSP and embed policy.
• Test camera denied, no camera, interrupted upload, expired token and mobile handoff.
• Verify webhooks with the current and previous secret during controlled rotation.
• Keep applicant URLs, documents and biometric data out of analytics/session replay.
• Monitor creation errors, webhook lag, completion rate and resume failures.
• Retain the previous SDK artifact for rollback.

Troubleshooting

Symptom	Check
401 or 403 creating an application	Key environment, scope, expiry and server-only configuration
Blank embedded frame	Exact frame-src, HTTPS origin, container height and browser console CSP error
Camera prompt never appears	Browser permission, Permissions-Policy, secure HTTPS context and iframe allow policy
Completion callback missing	Event origin, route cleanup and whether the applicant closed the page; rely on webhook
Link reports expired/revoked	Read invitation state, regenerate from the backend and deliver the replacement
Duplicate applications	Reuse one stable idempotency key for the same logical start attempt