API keys
Separate publishable keys, secret keys, client secrets, webhook secrets, and idempotency keys across sandbox and live environments.
0Bit integrations use several credential-like values. They are not interchangeable. Most integration bugs and security issues come from putting a server-only value in the browser, mixing sandbox and live credentials, or retrying a payment write with a new idempotency key.
Key types
| Value | Shape | Lives | Used for |
|---|---|---|---|
| Publishable key | pk_test_* / pk_live_* | Browser or mobile only where the product allows it. | Browser-safe bootstrap or discovery calls, such as 0Gate embed bootstrap. |
| Secret key | sk_test_* / sk_live_* | Server only. | Create/read privileged resources, create sessions, lock quotes, execute writes, retrieve protected records. |
| Client secret | Product-specific, session-scoped | Browser-safe for one object. | Binds a hosted experience to a server-created session. |
| Webhook secret | whsec_* | Server only. | Verify inbound webhook signatures. |
| Idempotency key | UUID or equivalent unique request key | Server-generated and stored with your logical write. | Deduplicate retries for state-changing writes. |
Secret keys never belong in client bundles
If a value starts with sk_ or whsec_, it must not appear in browser JavaScript, mobile apps, logs, screenshots, analytics, support tickets, or docs examples using real values.
Environment separation
| Product | Environment | Base URL | Key prefix |
|---|---|---|---|
| 0Gate | Sandbox | https://gate-api-sandbox.0bit.app/v1 | pk_test_*, sk_test_* |
| 0Gate | Production | https://gate-api.0bit.app/v1 | pk_live_*, sk_live_* |
| 0Gate | Local dev | http://localhost:4000/v1 | local/test values |
| 0Base | Sandbox | https://base-api-sandbox.0bit.app/v1 | review-only/test values |
| 0Base | Production | https://base-gate-api.0bit.app/v1 | review-only/live values |
| 0Pools | Production | https://pools-api.0bit.app/v1 | partner-confidential values |
Never use a live key against a sandbox host or a test key against a live host. Make host, key prefix, and deployment environment visible in internal logs so misconfiguration is obvious.
Server vs browser placement
The server owns privileged writes. The browser owns only presentation and product-approved bootstrap values.
Recommended configuration shape
# Sandbox server environment
OBIT_GATE_BASE_URL=https://gate-api-sandbox.0bit.app/v1
OBIT_GATE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OBIT_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Browser build environment
NEXT_PUBLIC_OBIT_GATE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThe exact variable names are up to your application. The security property is the split: server-only values stay in server runtime secrets, browser-safe values are explicitly prefixed for client exposure.
Rotation and revocation
| Action | Recommended process |
|---|---|
| Create a key | Create it for one environment and one product surface. |
| Deploy a key | Store it in a secret manager; deploy without committing it. |
| Rotate a key | Add new key, deploy, verify traffic, then revoke old key. |
| Revoke a key | Remove from secret stores and invalidate in partner/admin tooling. |
| Investigate exposure | Rotate immediately, search logs/builds, and audit recent API writes. |
Idempotency keys are not credentials
An idempotency key does not grant access. It identifies one logical write so retries do not create duplicate sessions, quotes, payment intents, rails, or refunds. Generate it on the server and store it with your order/workflow record.
| Write | Store idempotency with |
|---|---|
| Session creation | Your order, checkout, or ramp request. |
| Quote creation | Quote request and displayed terms. |
| Transact/execute | Accepted quote and resulting trade. |
| Payment intent/checkout write | Payment object and user/order reference. |
| Refund | Original payment intent and refund request. |
Common failure modes
| Symptom | Likely issue | Fix |
|---|---|---|
| Browser receives 401/403 on a privileged endpoint | Secret-key endpoint called from browser or wrong credential type. | Move call to server and expose only browser-safe values. |
| Embed bootstrap fails with 403 | Origin is not allow-listed or key/environment mismatch. | Register the exact origin and check test/live mode. |
| Webhook verification fails | Wrong webhook secret or body was parsed before verification. | Use raw body and the correct environment secret. |
| Duplicate sessions or quotes | Retried with a new idempotency key. | Persist and reuse the original key for the same logical write. |
| Support cannot trace a flow | Request id, event id, or object id was not logged. | Log those ids without logging secrets or PII. |
Related pages
Authentication
Review credential boundaries across products.
Environments
Keep sandbox, live, and local configuration separate.
Webhook signing
Verify signed events with server-only webhook secrets.
Idempotency
Retry state-changing writes without duplicates.
Support matrix
Check which products and environments each credential type applies to.