Security and safe fallbacks

Protect server-side project API keys and keep product feature checks resilient when the network is unavailable.

Server-side essentials

Security and runtime requirements for every integration.

Official SDKs are server-side only.

Never expose API keys in browser or client code.

Store API keys in environment variables.

The default fallback is false.

SDKs fail safely if SwitchPilot is unreachable.

Default cache TTL: 60 seconds.

Default stale-if-error window: 5 minutes.

API keys are server-side secrets

A project key can read every feature flag in that project. Never expose it in Client Components, browser code, logs, screenshots or public repositories.

Keys are shown only once

SwitchPilot displays a new project API key once. Copy it immediately and save it in a trusted password manager, hosting-provider secret store or deployment environment. SwitchPilot stores a hash of the key, not the raw value.

Use environment variables

.env

SWITCHPILOT_API_KEY=sp_live_...

Keep API keys server-side in environment variables or a secret store. Never commit keys or local environment files to source control.

Do not use NEXT_PUBLIC_

Never name the variableNEXT_PUBLIC_SWITCHPILOT_API_KEY. Next.js exposes NEXT_PUBLIC_ values to browser code, and SwitchPilot API keys must never be exposed in the browser.

Live UI updates without exposing your API key

For a live Next.js UI, the browser should poll a Route Handler in your own app. That server route uses @switchpilot/node to fetch flags from SwitchPilot, then returns only the safe boolean values the browser needs.

safe flow

Client Component
→ /api/flags
→ @switchpilot/node
→ SwitchPilot SDK endpoint

The project key remains in SWITCHPILOT_API_KEY on your server throughout this flow. The browser knows only your local/api/flagsURL and the returned flag values.

Never call SwitchPilot from the browser

unsafe — do not use

Client Component
→ SwitchPilot SDK endpoint directly with sp_live_...

Do not place an sp_live_... key in a Client Component, request header, browser bundle, orNEXT_PUBLIC_SWITCHPILOT_API_KEY.

Use a fail-closed fallback

switchpilot.ts

const flags = createSwitchPilot({
  apiKey: process.env.SWITCHPILOT_API_KEY!,
  fallback: false,
  timeoutMs: 2_000,
  cacheTtlMs: 60_000,
  staleIfErrorMs: 300_000,
});

The default fallback is false, which keeps an unavailable or unknown feature off. The SDK also fails safely on timeouts, invalid responses, non-successful status codes and ordinary network failures.

Understand caching

Each SDK client keeps successful flag responses in isolated memory for 60 seconds by default. Evaluations during that TTL are local. If a refresh fails, the Last Known Good configuration remains usable for a further five minutes by default; the fallback is used only after that window or before the first valid response. SDK redirects are disabled so Authorization is never forwarded automatically to another origin.

If a key is exposed

If an API key was shared or exposed accidentally, treat it as compromised and regenerate it from Project Settings. Update the secret in every server environment that uses it, restart those services, and remove the old key from logs or source history where possible.

API keys are shown once and existing keys cannot be recovered. All plans can regenerate a lost key. Regeneration immediately revokes only the selected environment's previous key; the project, flags, and Application Areas remain unchanged.

Paddle billing secrets

Only the Paddle client token and Price ID use NEXT_PUBLIC_. Keep the API key and webhook secret server-side. Billing webhooks are verified against the raw body, processed idempotently, and are the only mechanism allowed to grant Pro access.