SDK Integration
Copy-paste SDK integration decisions for production-safe rollout
Use a server-authoritative model with strict key boundaries, idempotent retries, and webhook reconciliation so engineering teams can ship safely and scale with predictable outcomes.
Architecture decision guide
Server boundaries
Create sessions and submit verification results from your backend only. Keep secret keys in your server-side secrets manager and issue short-lived model access tokens for browser biometric runtime.
Retries and idempotency
Use a unique request key per create/result-submission attempt and treat duplicate webhook events as expected. Retries should be safe and produce one authoritative session outcome.
Webhook-first lifecycle
Use verified webhook events for billing and final policy state. Client-side completion should be treated as provisional until backend reconciliation succeeds.
Install SDK and open API references
Start by installing the package, then keep API docs open while implementing auth, sessions, webhooks, and error handling.
CLI installation commands
pnpm add age-verify
npm install age-verify
yarn add age-verify
SDK source of truth in this repo
- NPM package: age-verify
- Canonical SDK docs: packages/age-verify/docs/INTEGRATION.md
- Canonical API reference: packages/age-verify/docs/API_REFERENCE.md
- SDK version in workspace: 0.6.2
- Payer mode: sponsor
- Integrator fees supported: no
API key lifecycle rules
- Create and rotate return plaintext API key once. Store it immediately in your secrets manager.
- Revoked keys fail authentication right away.
- Password reset changes portal login credentials only. It does not rotate API keys.
- Keep secret API keys on the backend. Do not ship them in browser bundles.
Integrator portal routes for merchant teams
- /integrator/signup
- /integrator/login
- /integrator/dashboard
- /integrator/password-reset
- /integrator/password-reset/complete
Release quality checklist
Keep version changes predictable and well documented.
Update support guidance whenever release behavior changes.
Use one release checklist for tests, webhooks, and telemetry.
Keep a changelog that ties technical changes to customer impact.
Pre-launch readiness review
- Security review: verify key isolation, model access token TTL, and signature validation logic in staging and production parity checks.
- Reliability review: test idempotency keys under forced retries and out-of-order webhook delivery before each major release.
- Policy review: confirm no-pass behavior, escalation routes, and support scripts are consistent with current legal and product requirements.
- Analytics review: monitor completion, retry, and no-pass trends by device and region to catch drift before it affects conversion.
- Finance review: reconcile meter events and verified session outcomes to ensure billing transparency and dispute readiness.
Change management notes
- Ship SDK and policy changes together so users and support teams see consistent behavior.
- Run regression checks before each release.
- After release, compare with baseline and roll back quickly if quality drops.
Keep the integration stable
If your backend lifecycle is weak, SDK quality will look worse in production than in testing.
Weekly reviews of telemetry and support trends help catch drift early.
Roll out major changes in stages with clear rollback rules.
End-to-end verification flow
- 1.Your app requests verification from your backend.
- 2.Your backend evaluates policy for the request context.
- 3.Your backend creates a verification session with a unique request key.
- 4.Your backend returns short-lived model access credentials to the client SDK.
- 5.The client runs liveness and age checks in-browser.
- 6.Your backend submits biometric or checkbox result and verifies signed outcome.
- 7.Webhook outcomes reconcile billing and lifecycle state for audit-safe operations.
SDK maturity checklist
- Use separate test and production keys.
- Test token expiry, retries, and network interruptions.
- Verify webhooks and duplicate handling in every release.
- Track performance by device type.
- Write one clear runbook for no-pass and escalation cases.
Common failure modes
- Camera or device capability failures on unsupported browsers.
- Model access token expiry before client verification completes.
- Network interruption between client completion and backend result submission.
- Duplicate webhook delivery without idempotent handlers.
- Billing-state blocks that prevent starting new sessions.
Troubleshooting FAQ
What should we do when a session expires mid-flow?
Issue a fresh short-lived token from your backend and restart the client flow with a clear user message. Do not reuse expired tokens.
How should retries work for result submission calls?
Retry result submission with the same idempotency key so duplicate attempts converge on one authoritative outcome.
Is client success enough to unlock access?
No. Access should be granted only after backend result submission and signature verification complete successfully.
How do we debug billing mismatches?
Compare internal session records with webhook events and meter emissions, then reconcile identityMode and event timestamps.
Ready to integrate?
Plan the work by phase
The SDK is only one part of the system. Reliable results come from strong backend handling.
Do not optimize for pass rate only. Also track retries, support load, and no-pass clarity.
Keep a change log for policy updates so teams can debug quickly when outcomes shift.