Environment Variables
Configure test and live 0Bit values without leaking server-only credentials to the browser.
Environment variables are part of the security boundary. A clean setup makes it obvious which values live on the server, which values are safe in browser bundles, and which values change between sandbox and production.
Baseline variables
| Variable | Lives | Example | Purpose |
|---|---|---|---|
OBIT_GATE_API_BASE_URL | Server | https://gate-api-sandbox.0bit.app/v1 | Raw REST base URL for 0Gate server calls. |
OBIT_SECRET_KEY | Server | sk_test_... | Secret key for privileged API calls. |
NEXT_PUBLIC_OBIT_PUBLISHABLE_KEY | Browser | pk_test_... | Publishable key for hosted/embed bootstrap where allowed. |
OBIT_WEBHOOK_SECRET | Server | whsec_test_... | Secret used to verify inbound webhook signatures. |
OBIT_ENVIRONMENT | Server and build config | sandbox | Makes the selected mode explicit in logs and SDK config. |
Use framework-specific browser prefixes only for publishable values. For example, NEXT_PUBLIC_, VITE_, and PUBLIC_ values are bundled into client code in common frameworks. Never place sk_* or whsec_* behind those prefixes.
Development example
# .env.local
OBIT_ENVIRONMENT=sandbox
OBIT_GATE_API_BASE_URL=https://gate-api-sandbox.0bit.app/v1
OBIT_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_OBIT_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OBIT_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxxxxxxxxxxxxxxProduction example
# .env.production
OBIT_ENVIRONMENT=production
OBIT_GATE_API_BASE_URL=https://gate-api.0bit.app/v1
OBIT_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_OBIT_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OBIT_WEBHOOK_SECRET=whsec_live_xxxxxxxxxxxxxxxxxxxxxxxxTest keys must call sandbox. Live keys must call production. Treat a mode mismatch as a configuration bug, not a recoverable user error.
Product-specific hosts
0Bit products are separate surfaces. Do not assume one host covers every product.
| Product | Typical base URL shape | Notes |
|---|---|---|
| 0Gate | https://gate-api-sandbox.0bit.app/v1 or https://gate-api.0bit.app/v1 | Default first integration path. |
| 0Pools | Product/API-reference host when your org is approved for pool access. | Access is entitlement and pool-config gated. |
| 0Base | Product/API-reference host where merchant payment objects are enabled. | 0Base partner API pages are not published yet; use account enablement notes for exact fields. |
| 0Link | Product/API-reference host where route/workflow review is enabled. | Keep source and venue details out of client config. |
If you use SDK constructors, check whether the SDK expects the origin or the /v1 base URL. The 0Gate SDK uses the origin; raw REST examples use /v1.
Recommended naming by layer
| Layer | Recommended values |
|---|---|
| Backend service | OBIT_SECRET_KEY, OBIT_GATE_API_BASE_URL, OBIT_WEBHOOK_SECRET, OBIT_ENVIRONMENT |
| Frontend build | NEXT_PUBLIC_OBIT_PUBLISHABLE_KEY or equivalent publishable-only name |
| Worker/webhook service | OBIT_WEBHOOK_SECRET, OBIT_SECRET_KEY if trusted reads are needed |
| CI sandbox tests | sk_test_*, pk_test_*, sandbox host, test webhook secret |
| Production | sk_live_*, pk_live_*, production host, live webhook secret |
Allowed domains and return URLs
Hosted and embedded flows can be gated by allowed origins and return URLs. Keep these values explicit in your environment setup:
| Value | Example | Why |
|---|---|---|
| Local origin | http://localhost:3000 | Lets the widget bootstrap during local development. |
| Staging origin | https://staging.partner.example | Lets QA test realistic redirects and webhooks. |
| Production origin | https://app.partner.example | Required before live traffic. |
| Return URL | https://app.partner.example/checkout/done | User returns after hosted or redirected flow. |
| Webhook URL | https://api.partner.example/webhooks/0bit | 0Bit sends signed events to your backend. |
Leak prevention
| Risk | Prevention |
|---|---|
| Secret key in browser bundle | Prefix only publishable values with framework public prefixes. Run bundle scans in CI. |
| Webhook secret in logs | Redact whsec_*, request headers, and raw config dumps. |
| Keys copied into examples | Use placeholder values in docs and demos. |
| Test/live mix | Validate key prefix and API host on application start. |
| Missing webhook secret | Fail startup for webhook workers if OBIT_WEBHOOK_SECRET is absent. |
Startup validation example
const baseUrl = process.env.OBIT_GATE_API_BASE_URL!;
const secretKey = process.env.OBIT_SECRET_KEY!;
if (baseUrl.includes('sandbox') && !secretKey.startsWith('sk_test_')) {
throw new Error('Sandbox base URL requires sk_test_*');
}
if (!baseUrl.includes('sandbox') && !secretKey.startsWith('sk_live_')) {
throw new Error('Production base URL requires sk_live_*');
}