Environment-Based Key Management Explained

Modern applications run in multiple environments. Your development laptop, staging servers, and production infrastructure all have different requirements. Here's how to configure IBYOK for each.

Understanding Environments

IBYOK recognizes three environments:

The environment is determined by the `NODE_ENV` environment variable on the External API server.

Configuration Levels

1. Environment Defaults

Set the default mode for each environment in your dashboard:

**Development → Mock**

• Saves API costs during development

• Prevents accidental data pollution

• Faster iteration without rate limits

**Staging → Mock (recommended) or Live**

• Mock for automated testing

• Live for final pre-release validation

**Production → Live**

• Real keys for real users

• Never mock in production

2. Per-Key Overrides

Sometimes you need exceptions. Per-key overrides let you:

• Test a new provider integration with real keys in development

• Keep a specific key mocked in staging while others are live

• Handle special cases without changing environment defaults

To set an override:

1. Navigate to the Keys page

2. Click the settings icon on the key

3. Select the override for each environment

3. Infrastructure Guardrails

Server administrators can enforce settings that override everything:

# Force development to always use mock

DEV_MODE_FORCED=mock

# Force production to always use live

PROD_MODE_FORCED=live

# Prevent users from enabling mock in production

PROD_MOCK_ALLOWED=false

Resolution Priority

When determining the effective mode for a key, IBYOK checks in order:

1. **Guardrail** - If set, this always wins

2. **Key Override** - Per-key setting for this environment

3. **Environment Default** - Your configured default

The API response tells you which level determined the mode:

{

"modeInfo": {

"environment": "development",

"effectiveMode": "mock",

"source": "tenant_setting"

}

}

Sources:

• `guardrail_override` - Server configuration forced this

• `key_override` - Per-key setting applied

• `tenant_setting` - Environment default used

Practical Setup Guide

Step 1: Set Environment Defaults

1. Go to the Keys page in your dashboard

2. Find the Environment Settings section

3. Configure:

• Development: Mock

• Staging: Mock

• Production: Live

Step 2: Store Your Keys

Add your API keys for each provider you use. They'll all follow your environment defaults initially.

Step 3: Handle Mode in Your App

Check the mode in API responses:

const response = await fetch(`${IBYOK_API}/external/keys/${keyId}/value`, {

headers: { Authorization: `Bearer ${token}` }

});

const data = await response.json();

if (data.modeInfo.effectiveMode === 'mock') {

console.log('Running with mock key - API calls will fail');

}

Step 4: Override When Needed

Testing a new Anthropic integration? Override just that key:

1. Click settings on your Anthropic key

2. Set Development to "Live (override)"

3. Test with real API calls

4. Reset to "Inherit" when done

Common Patterns

Pattern: Safe CI/CD Testing

# GitHub Actions

env:

NODE_ENV: staging

IBYOK_ACCESS_TOKEN: ${{ secrets.IBYOK_TOKEN }}

# Staging defaults to mock, so tests don't cost money

Pattern: Gradual Rollout

1. Add new provider key to IBYOK

2. Override to Live in development only

3. Test thoroughly

4. Remove override (inherits mock)

5. Deploy to production (uses live)

Pattern: Cost Control

Keep expensive providers (GPT-4, Claude) mocked by default. Override to live only when specifically testing those integrations.

Environment-based key management gives you control without complexity. Set sensible defaults, use overrides sparingly, and let the system handle the rest.