We Built a Public API With Test/Live Key Isolation. Here's How It Works Under the Hood.

Most API platforms give you test keys and live keys. Stripe does it. Twilio does it. It feels like magic - you test against a sandbox, flip to production, and nothing leaks.

We just shipped a Public REST API for PaperLink - a document sharing and analytics platform. Our test/live isolation uses the simplest possible architecture: one boolean column in the same table. No separate databases, no shadow schemas, no data duplication.

Here's how it works, why it's safe, and what the actual requests look like.

The two keys

When you create an API key in PaperLink, you pick a mode:

• Live - operates on production data
• Test - operates on an isolated sandbox

The keys look different on purpose:

Live: pk_live_AbC123XyZ789...
Test: pk_test_xyZ987AbC321...

You see which one you're using before you paste it anywhere.

What "isolation" actually means

Test and live products live in the same Postgres table. The only difference is a test_mode boolean column:

-- Simplified schema
CREATE TABLE products (
  id          UUID PRIMARY KEY,
  team_id     UUID NOT NULL,
  name        TEXT NOT NULL,
  unit_price  DECIMAL NOT NULL,
  currency    TEXT NOT NULL,
  test_mode   BOOLEAN DEFAULT false,
  status      TEXT DEFAULT 'ACTIVE',
  created_at  TIMESTAMP DEFAULT now()
);

CREATE INDEX products_team_test_mode_status_idx
  ON products (team_id, test_mode, status);

Every query includes test_mode in the WHERE clause. There is no code path that reads products without filtering by mode.

Live demo: create, read, isolate

Create a product with a test key:

curl -X POST https://app.paperlink.online/api/v1/products \
  -H "Authorization: Bearer pk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Product", "unitPrice": 29.99, "currency": "USD"}'

{
  "data": {
    "id": "4d574270-7cc5-4234-865e-f78bea3915bf",
    "name": "Test Product",
    "unitPrice": 29.99,
    "currency": "USD",
    "status": "ACTIVE",
    "createdAt": "2026-04-30T14:50:30.601Z"
  }
}

Now try to read that product with a live key:

curl https://app.paperlink.online/api/v1/products/4d574270-... \
  -H "Authorization: Bearer pk_live_xxx"

{
  "error": {
    "type": "not_found_error",
    "code": "product_not_found",
    "message": "Product not found",
    "request_id": "ef23c7f1-6018-4281-b1bd-d1774e45b6bd"
  }
}

404 - not 403. The live key doesn't know the test product exists. We return 404 instead of 403 deliberately: a 403 would confirm "this resource exists but you can't access it", which leaks information.

List all products with the live key:

curl https://app.paperlink.online/api/v1/products \
  -H "Authorization: Bearer pk_live_xxx"

{
  "data": {
    "data": [],
    "hasMore": false,
    "nextCursor": null
  }
}

Empty. The test product is invisible to live keys.

How the isolation flows through the code

The architecture has four steps between the HTTP request and the database query:

1. Bearer token arrives
2. Token is hashed (HMAC-SHA256) and looked up in api_keys table
3. Key's mode (LIVE or TEST) is extracted
4. Mode is converted to testMode boolean and injected into every query

In code, the flow looks like this:

// Route handler extracts mode from authenticated key
const testMode = getTestModeFromAuth(authResult.auth);

// Use case receives it as an explicit parameter
const result = await listProductsUseCase.execute({
  teamId: authContext.teamId,
  testMode, // true for test keys, false for live keys
});

// Repository always filters by testMode
const products = await prisma.product.findMany({
  where: {
    teamId: filters.teamId,
    testMode: filters.testMode, // always present, never optional
    status: filters.status,
  },
});

The testMode parameter is not optional. It's not a default. It's required in every repository method that touches products. If you forget it, TypeScript fails at compile time.

SKU uniqueness is mode-scoped

You can have the same SKU in test and live mode:

UNIQUE (sku, team_id, test_mode)

This means your test suite can mirror production SKUs exactly without collisions. When you switch from test to live, the same product catalog structure works.

Test data auto-cleans after 90 days

Test products that haven't been updated in 90 days get automatically archived by a daily cron job:

// Daily cron job
const staleProducts = await productRepository.findStaleTestProducts(cutoffDate);
// cutoffDate = now - 90 days
// WHERE testMode = true AND status = ACTIVE AND updatedAt < cutoffDate

await productRepository.archiveMany(staleProductIds, teamId);

If your CI pipeline creates and updates test products regularly, they stay alive. If you stop using them, they clean themselves up after 90 days.

What about deletes?

DELETE /api/v1/products/{id} is a soft delete - it sets status: ARCHIVED. The product still exists in the database (invoices may reference it), but it disappears from the default list.

A test key can only archive test products. A live key can only archive live products. Cross-mode delete returns 404, same as cross-mode read.

# Test key trying to delete a live product
curl -X DELETE https://app.paperlink.online/api/v1/products/{live-product-id} \
  -H "Authorization: Bearer pk_test_xxx"

# 404 - doesn't know it exists

The full API contract

Why Products as the first resource?

PaperLink has Documents, Companies, Links, DataRooms - all more complex than Products. We deliberately picked the simplest entity to ship first.

Products have ~20 fields (name, price, SKU, tax, inventory) but no complex business logic - no state machines, no multi-step workflows, no PDF generation. Documents have line items, tax calculations, status transitions, and PDF rendering. Companies have VAT regulation logic across jurisdictions. Links have sharing permissions, password protection, expiration rules, and analytics tracking.

The goal was not to ship a useful Products API. The goal was to build the infrastructure: authentication, rate limiting, idempotency, error format, test/live isolation, Scalar docs, cursor pagination. All of that had to be designed, tested, and proven on a real resource.

Now every future resource we add - Documents, Companies, Links - automatically inherits all of it. Adding a new CRUD resource is mechanical: write the use case, plug into the existing middleware chain, done. The hard part is already shipped.

Why not separate databases?

We considered three isolation strategies:

We chose the boolean column because:

1. One migration - adding a column with a default is non-destructive
2. One set of indexes - compound index (team_id, test_mode, status) covers both modes efficiently
3. TypeScript enforces it - testMode is required in repository method signatures, not optional
4. It's what Stripe does - and it works at their scale

The risk with a boolean column is forgetting to include it in a query. We mitigate that by making testMode a required parameter in every repository method signature. If someone writes a new query without it, the code doesn't compile.

Try it

Sign up at app.paperlink.online, go to Settings > API Keys, create a test key, and run:

curl -H "Authorization: Bearer YOUR_TEST_KEY" \
  https://app.paperlink.online/api/v1/products

Interactive docs are at app.paperlink.online/api/docs.

The API currently supports Products CRUD. More resources (Documents, Companies, Links) are coming - each one automatically inherits the same test/live isolation, rate limiting, idempotency, and error format.