Skip to main content

Sandbox mode

Sandbox lets you create flows, run verifications, and receive webhooks against synthetic / non-production data. Production uses the same API and verification hosts; the difference is the sandbox flag on each request and the /sandbox path on the hosted UI.

For the go-live checklist, see Sandbox and go-live. For hosts, see Environment setup.

What “sandbox” means​

LayerHow sandbox is expressed
DashboardToggle the organization / UI into sandbox when building flows and reviewing sandbox results
API query parameter?sandbox=true or ?sandbox=false on SDK HTTP endpoints (required on create, next-step, step completion, list results, …)
npm SDKisSandbox: true | false on session helpers (mapped to the sandbox query param)
Hosted session URLSandbox: https://verify.zyphe.com/sandbox/flow/<flowSlug>?… · Production: https://verify.zyphe.com/flow/<flowSlug>?…
API hostUnchanged: still https://api.zyphe.com

Sandbox is not a separate base URL on production accounts. Setting ZYPHE_BASE_URL=https://docs.zyphe.com or inventing a sandbox.api… host will not work.

Rules that must match​

Treat these as one unit for a given verification:

  1. The flow and data you intend to use live in sandbox or production in the dashboard.
  2. Every API call for that verification uses the same sandbox value (true with sandbox, false with production).
  3. The session URL you open in the browser / WebView uses the matching path (/sandbox/flow/… vs /flow/…).
  4. Webhooks for that run go to the endpoint configured on that flow; process sandbox and production separately if both are active.
Create / complete APIHosted UI pathIntended mode
sandbox=true/sandbox/flow/<slug>?…Sandbox
sandbox=false/flow/<slug>?…Production

Mismatch behavior​

If the sandbox query parameter does not match the environment the flow and verification request were created in, the API returns an error (typically a client error with a structured errorTag such as flow_not_found, verification_request_not_found, or a validation / permission failure). Do not expect a silent success.

Common mistakes:

  • Creating the session with sandbox=true, then opening https://verify.zyphe.com/flow/… (missing /sandbox)
  • Copy-pasting a production curl with sandbox=false while the dashboard is in sandbox
  • Reusing a production secret key / flow ID against the wrong mode without aligning sandbox

Always set the flag explicitly on every call. Do not rely on defaults from outdated snippets.

Session URL examples​

Sandbox

https://verify.zyphe.com/sandbox/flow/<flowSlug>?zypheVr=<verificationRequest.id>&zypheToken=<zypheToken>&zypheAccessSig=<zypheAccessSig>&zypheEmail=<email>

Production

https://verify.zyphe.com/flow/<flowSlug>?zypheVr=<verificationRequest.id>&zypheToken=<zypheToken>&zypheAccessSig=<zypheAccessSig>&zypheEmail=<email>

How to obtain the tokens: Backend API integration.

Dashboard vs API​

  • Building and testing in the dashboard sandbox mode only affects dashboard-created runs and the sandbox data plane.
  • Programmatic integrations must still send sandbox=true on API calls for sandbox sessions.
  • Switching the dashboard to production does not automatically convert your backend; update keys, sandbox=false, and session URL composition together.