App ID

Public UUID identifying your application. Safe to embed in mobile apps alongside publishable keys.

Publishable Key (pk_live_)

Client-safe key used only for POST /v1/sdk/token. Cannot create verifications directly. Bound to registered Android package + SHA256.

Secret Key (sk_live_)

Server-only key for POST/GET/DELETE /v1/verifications. Never ship in mobile binaries or front-end code.

SDK Token (JWT)

Short-lived JWT (~180s, configurable via sdk_token_ttl_seconds). Issued by /v1/sdk/token. Used as Bearer token for verification API — same permissions as secret key for that app.

Dashboard JWT

Access + refresh tokens for dashboard login. Include in Authorization: Bearer for org and app management routes.

Package Name

Android applicationId registered via billing settings or POST /v1/apps/:id/android-signatures. SDK token rejects mismatched package with package_mismatch.

Android SHA256

64-character hex fingerprint of your signing certificate. Get via keytool -list -v -keystore …. Unregistered fingerprints return signature_not_registered.

HTTPS

Webhook URLs must use HTTPS. Private/reserved IPs are rejected. See webhook validation errors.

Test Keys (sk_test_ / pk_test_)

Test keys (pk_test_ / sk_test_) use real gateways and consume credits — same missed-call flow as live. Never use test keys in production builds shipped to users. Test/Live refers to API keys, not “testing Shernova”.

Receipt JWT

Signed proof of verification. Verify server-side via POST /v1/receipts/verify with secret key. Each receipt JWT is single-use — replay returns receipt_already_used (SH_014).

Replay Protection

SDK token requests require a unique nonce (8–128 chars). SDK JWT expires quickly. Receipt JWTs are single-use with server-side replay detection.

Token Lifetime

Webhook Signatures

HMAC-SHA256 of raw JSON body using webhook secret. Header: X-Shernova-Signature: sha256=<hex>.

How verification proves phone ownership

Shernova does not send SMS codes or read the user's call log. Ownership is proven when the same phone number the user entered places an outbound missed call to the assigned gateway number during an active session.

1. Your app creates a session with the user's phone in E.164 format.
2. Shernova assigns a gateway number and holds one billing credit.
3. The user must call from that exact phone before the session TTL expires (default 300 seconds).
4. The gateway device reports the incoming caller ID; the API matches the caller to the session.
5. On match, status becomes verified and a signed receipt JWT is issued.

This prevents someone with only the gateway number from verifying — they must control the phone number registered in the session. Calls are not recorded; only caller ID metadata is used for matching. See Architecture for the full pipeline.

Security checklist

Store secrets in a vault, rotate keys after incidents, verify webhook signatures, and use HTTPS everywhere. See Best Practices for integration guidance.