API Keys

API Keys Reference

Learn how to generate, manage, and securely authenticate requests to the Arionys billing engine using per-product SaaS API keys.

Key Structure & Formats

Each key carries a prefix that identifies its environment — never mix sandbox and production keys.

Sandbox Environment

sb_test_…

For local integrations, staging environments, or sandbox-level testing. Does not process real payments.

Production Environment

sb_live_…

For live billing processes and active Paddle payment gateway events. Guard these carefully.

Security Best Practices

Server-Side Integration Only

Never embed API keys in client-side code (React bundles, Vue components, etc.). Store them in server-side environment variables (.env) and call the billing engine only from API routes or server functions.

Cryptographic Database Storage

The engine never stores raw keys. It persists a SHA-256 hash (apiKeyHash) and displays only a short hint (e.g. sb_live_a…cdef). Incoming keys are hashed and compared with timingSafeEqual to block timing attacks.

Key Rotation

If a key leaks (public repo, client log), go to Admin Dashboard → Products → select your product → Rotate API Key. The old key is instantly invalidated and a new one is issued.

Verification Implementation

Here is exactly how the billing engine matches incoming API keys against the database — using SHA-256 hashing and a constant-time comparison to eliminate timing side-channel leaks.

typescript

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 side-channel attacks
  return crypto.timingSafeEqual(
    Buffer.from(incomingHash, "utf-8"),
    Buffer.from(hashedKey, "utf-8")
  );
}