System Overview
Shernova connects your application, mobile SDK or server API, billing credits, physical gateway phones, and optional webhooks into one verification pipeline.
Components
| Component | Role |
|---|---|
| Developer Dashboard | Manage apps, keys, billing, sessions, team |
| REST API | Create and query verification sessions |
| Flutter SDK | Token exchange + UI + polling |
| Billing Engine | Hold → Capture/Release per session |
| Gateway Android App | Receives calls, posts ring events |
| Webhook Delivery | POST signed events to your HTTPS endpoint |
Session Lifecycle
Authentication Layers
- Dashboard JWT — browser sessions for dashboard and org management
- Secret key (
sk_live_/sk_test_) — server-side verification API; test keys use real gateways and consume credits - Publishable key (
pk_live_/pk_test_) — SDK token exchange only - SDK JWT — short-lived (~180s), used like secret key for verifications
- Gateway token —
X-Shernova-Gateway-Tokenfor gateway devices only
Verification Data Flow
- App requests verification with phone number in E.164 format
- API validates billing (active, not frozen, credits available) and holds 1 credit
- API selects an online gateway and returns
gateway_phone_number - User places missed call from the same phone number
- Gateway app sends ring event; API matches caller tail to session
- Session status becomes
verified; credit is captured; webhook is queued
Default session TTL is 300 seconds. Gateway must heartbeat within 120 seconds to stay online.
Test keys vs live keys
- Test keys (
sk_test_,pk_test_) use real Android gateways and consume credits - Live keys (
sk_live_,pk_live_) — same verification flow for production users - Dashboard — Sessions page shows key type (test / live) and session status
Receipts (server proof)
- After
verified, issue receipt:POST /v1/verifications/:id/receipt - Send JWT receipt to your backend
- Verify once server-side:
POST /v1/receipts/verifywithsk_*— replay returns SH_014