Sandbox and Production

One base URL, two environments

There is no separate sandbox hostname and no ?test=true parameter. The key you send determines which environment you are in, and nothing else about the request changes.

# Sandbox
curl https://countdownshare.com/api/v1/timers \
  -H "Authorization: Bearer cs_test_..."

# Production — same URL, same path, different key
curl https://countdownshare.com/api/v1/timers \
  -H "Authorization: Bearer cs_live_..."

This is deliberate. A separate sandbox host is a second thing that can drift, and drift between test and live environments is how integrations pass every test and then fail on launch day. Here there is one deployment, one codebase, and one contract.

What actually differs

The behaviour of every endpoint is identical. What changes is the ceiling on volume and whether a timer can become public.

How strict the isolation is

Complete. A Sandbox key presented with a Production timer ID does not return a permission error — it returns not_found, because from that key's perspective the timer does not exist. There is no query the API can be asked that crosses the boundary.

A practical consequence: you cannot promote a Sandbox timer to Production. There is no copy operation, and there should not be — a timer that was created for a test should not quietly become one your customers see. Recreate it with a Production key.

Testing webhooks locally

Sandbox accepts http:// destination URLs specifically so you can point a destination at a local tunnel — ngrok, Cloudflare Tunnel, or your own — while you develop the handler. Production requires HTTPS.

Private, loopback, and link-local addresses are rejected in both environments, so http://localhost:3000 will not be accepted. Use the public tunnel URL the tool gives you rather than the address it forwards to.

Going live

The code change is one environment variable. Everything below is the part people forget.

Configuration

// Environment is a deployment concern, not a code branch.
// One variable changes everything; nothing else in your code differs.
const key = process.env.COUNTDOWNSHARE_API_KEY;

// A guard worth having: fail loudly at boot rather than
// quietly writing test data to a live account.
if (process.env.NODE_ENV === "production" && !key?.startsWith("cs_live_")) {
  throw new Error("Production build is holding a non-production API key");
}

Checklist

• Swap the key

  A cs_live_ key in your production secret store, and the Sandbox key removed from it.

• Add publish: true

  Production timers are still drafts by default. A timer nobody can see is the most common launch-day surprise.

• Re-register destinations

  Destinations do not cross environments. Create the Production one with its public HTTPS URL and store the new signing secret.

• Re-create webhook rules

  Rules belong to a timer, so Production timers need their own rules attached.

• Recheck rate limits

  Production allows ten times the Sandbox rate. If you built throttling around 30 rpm, you are now leaving throughput unused.

• Confirm the monthly allowance

  GET /usage reports the limit and what remains on the current plan. Check it matches the volume you expect.

• Handle quota_exhausted

  It is a 429, like the rate limit, but it does not clear on its own. Make sure your code distinguishes them.