Skip to main content

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​

PurposeProduction URLNotes
API base URLhttps://api.zyphe.comAll backend HTTP calls (/sdk/..., session create, step completion, flow results, …). Send x-api-key here.
Dashboardhttps://verify.zyphe.comSign in to configure flows, API keys, webhooks, and review results. Not an API host.
Verification / hosted UIhttps://verify.zyphe.comUser-facing verification session pages. Open this in a browser, redirect, iframe, or mobile WebView.
Documentationhttps://docs.zyphe.comHuman- 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.

Wrong host = guaranteed failure

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:

ModeSession URL shape
Sandboxhttps://verify.zyphe.com/sandbox/flow/<flowSlug>?…
Productionhttps://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
VariableUsed for
ZYPHE_API_BASE_URLPrefix for POST /sdk/flow/{flowId}/vr/create and other API paths
ZYPHE_SECRET_API_KEYx-api-key header on server-side calls (API keys). Must come from the environment ZYPHE_SANDBOX names
ZYPHE_VERIFY_BASE_URLBuilding the user-facing session URL
ZYPHE_FLOW_IDPath parameter on create / next-step endpoints
ZYPHE_SANDBOXQuery 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 as zyphe_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:

environmentAPIHosted UI / dashboard
production (default)https://api.zyphe.comhttps://verify.zyphe.com
localhttp://localhost:3000http://localhost:5173

isSandbox / sandbox is independent of environment. Call the production API hosts with sandbox=true and a sandbox API key for synthetic data.