Environment setup
Use this page as the single source of truth for hosts, environment variables, and which URL does what. Most failed first integrations come from pointing the API client at the wrong host (including the documentation site).
Hosts
| Purpose | Production URL | Notes |
|---|---|---|
| API base URL | https://api.zyphe.com | All backend HTTP calls (/sdk/..., session create, step completion, flow results, …). Send x-api-key here. |
| Dashboard | https://verify.zyphe.com | Sign in to configure flows, API keys, webhooks, and review results. Not an API host. |
| Verification / hosted UI | https://verify.zyphe.com | User-facing verification session pages. Open this in a browser, redirect, iframe, or mobile WebView. |
| Documentation | https://docs.zyphe.com | Human- and LLM-readable docs only. Never send API traffic here. |
The dashboard and hosted verification UI share https://verify.zyphe.com. Sandbox vs production is a flag, a URL path, and a set of API keys, not a different host. See Sandbox mode.
https://docs.zyphe.com is not an API base URL. Requests to the docs site never authenticate, never create sessions, and will not return verification results. Always set the API base URL to https://api.zyphe.com.
Sandbox vs production hosts
Sandbox is not a different API host. You use the same https://api.zyphe.com base URL and pass sandbox=true (or isSandbox: true in the SDK) so the call targets sandbox data for your organization.
API keys, on the other hand, belong to one environment. A key created while the dashboard is in sandbox only works with sandbox=true, and a production key only with sandbox=false: a production key sent with sandbox=true is rejected with invalid_api_key. Keep one key per environment and switch both together.
The hosted UI uses a path prefix for sandbox sessions:
| Mode | Session URL shape |
|---|---|
| Sandbox | https://verify.zyphe.com/sandbox/flow/<flowSlug>?… |
| Production | https://verify.zyphe.com/flow/<flowSlug>?… |
Details: Sandbox mode.
Ready-to-copy environment variables
# Backend API (server-side only)
ZYPHE_API_BASE_URL=https://api.zyphe.com
ZYPHE_SECRET_API_KEY=zyphe_sk_... # secret key from the same environment as ZYPHE_SANDBOX; never ship to mobile or browser
# Hosted verification UI (for composing session links / WebView)
ZYPHE_VERIFY_BASE_URL=https://verify.zyphe.com
# Flow and mode
ZYPHE_FLOW_ID=00000000-0000-0000-0000-000000000000
ZYPHE_SANDBOX=true # must match how the flow/session is used
# Optional: only if you use the npm SDKs
# production → api.zyphe.com + verify.zyphe.com
ZYPHE_SDK_ENVIRONMENT=production
| Variable | Used for |
|---|---|
ZYPHE_API_BASE_URL | Prefix for POST /sdk/flow/{flowId}/vr/create and other API paths |
ZYPHE_SECRET_API_KEY | x-api-key header on server-side calls (API keys). Must come from the environment ZYPHE_SANDBOX names |
ZYPHE_VERIFY_BASE_URL | Building the user-facing session URL |
ZYPHE_FLOW_ID | Path parameter on create / next-step endpoints |
ZYPHE_SANDBOX | Query sandbox=true|false on API calls; must match session URL path |
Authentication header
x-api-key: zyphe_sk_...
Content-Type: application/json
- Backend / server / pure HTTP: use a secret key (
zyphe_sk_…). A secret key is shown in full only once, when you create it. Store it in your secret manager then: afterwards the dashboard shows only a hint such aszyphe_sk_…a1b2, enough to recognize the key but not to use it. - Browser SDK only: publishable key (
zyphe_pk_…) with allowed origins. - See API keys and API errors for
invalid_api_key.
npm SDK environment mapping
If you use @zyphe-sdk/node or @zyphe-sdk/core, SDKOptions.environment selects the hosts above:
environment | API | Hosted UI / dashboard |
|---|---|---|
production (default) | https://api.zyphe.com | https://verify.zyphe.com |
local | http://localhost:3000 | http://localhost:5173 |
isSandbox / sandbox is independent of environment. Call the production API hosts with sandbox=true and a sandbox API key for synthetic data.
Related
- Backend API integration — create a session without the npm SDK
- API keys
- Sandbox mode
- OpenAPI reference