Skip to main content

API Keys

API keys authenticate requests from the BreakGround Runtime SDK and server-to-server integrations. Manage keys from Settings > API Keys.

Key Format​

All BreakGround API keys follow this format:

wfx_ + 64 hexadecimal characters

Example: wfx_a1b2c3d4e5f6... (68 characters total). Keys are hashed with SHA-256 before storage -- the plaintext key is shown only once at creation time.

Creating a Key​

  1. Navigate to Settings > API Keys.
  2. Click Create API Key.
  3. Enter a descriptive name (e.g., "Production SDK" or "Staging").
  4. Copy the key immediately. It will not be shown again.

Each company can have multiple active API keys, allowing you to use separate keys for different environments.

Key Permissions and Scopes​

API keys grant access to SDK endpoints including:

  • Configuration -- Fetch published flows and content for the SDK.
  • Events -- Submit user events (page views, clicks, flow interactions).
  • Identity -- Resolve and identify end users.

Dashboard management endpoints require JWT authentication, not API keys.

Rotating Keys​

To rotate a key without downtime:

  1. Create a new API key in the dashboard.
  2. Deploy the new key to your application.
  3. The old key remains valid for a 24-hour grace period after you revoke it.
  4. After 24 hours, the old key is permanently invalidated.

Revoking Keys​

Click Revoke next to any key in the API Keys list. Revoked keys enter the 24-hour grace window before full invalidation. To revoke immediately without a grace period, select Revoke Immediately.

Security Best Practices​

  • Store API keys in environment variables, never in client-side source code.
  • Use the X-API-Key header rather than query parameters to avoid key exposure in server logs.
  • Rotate keys on a regular schedule and after any suspected compromise.
  • Use separate keys per environment (development, staging, production).
  • Monitor API key usage from the dashboard to detect anomalous traffic.