API Keys Reference

Learn how to generate, manage, and securely authenticate requests using SaaS API keys.

Key Structure & Formats

API Keys are high-entropy keys used to authenticate your external SaaS products with the central billing engine. Each key starts with a specific prefix indicating the environment:

Sandbox Environment

sb_test_...

For local integrations, staging, or sandbox-level testing.

Production Environment

sb_live_...

For live billing processes and active payment gateway events.

Security Best Practices

Server-Side Integration Only

Never embed or call API keys directly from your client-side frontend code (such as React, Vue, or next client bundles). Keep them stored securely in server-side environment variables (`.env`) and perform checks inside API routes or server endpoints.

Cryptographic Database Storage

For maximum security, the central billing database never stores raw API keys. Instead, the engine creates a SHA-256 hash of the key (`apiKeyHash`) and displays only a secure hint (e.g. `sb_live_a...cdef`) on the dashboard. Incoming keys are hashed and validated using a constant-time cryptographic compare (`timingSafeEqual`) to prevent timing side-channel attacks.

Key Rotation

If a key is accidentally exposed in a public repository or client log, navigate immediately to the **Admin Dashboard** (`/admin`), go to **Products**, select your product, and click **Rotate API Key**. This will instantly invalidate the old key and issue a new one.

Verification Implementation

Here is how the billing engine securely matches client requests with database keys:

import crypto from "crypto";

export function hashApiKey(rawKey: string): string {
  return crypto.createHash("sha256").update(rawKey).digest("hex");
}

export function verifyApiKey(rawKey: string, hashedKey: string): boolean {
  const incomingHash = hashApiKey(rawKey);
  // Constant time comparison prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(incomingHash, "utf-8"),
    Buffer.from(hashedKey, "utf-8")
  );
}