Environments

Truthlock provides separate environments for development and production. Understanding the differences is crucial for proper integration.

Base URLs

Environment	API Base URL	Console URL
Sandbox	`https://sandbox-api.truthlocks.com`	`https://console.truthlocks.com`
Production	`https://api.truthlocks.com`	`https://console.truthlocks.com`

Important: API keys are environment-specific. A development API key (prefix tl_dev_) will not work in production, and vice versa.

Environment Differences

Feature	Sandbox	Production
API Key Prefix	`tl_dev_`	`tl_live_`
Issuer Auto-Approval	✅ Issuers are auto-approved	❌ Requires governance approval
Rate Limits	1,000 req/min	Based on tier (60-unlimited)
Daily Quota	10,000 attestations	Based on tier
Data Retention	30 days	Permanent
SLA	Best effort	99.9% uptime
Transparency Log	Ephemeral (reset weekly)	Permanent, append-only

API Key Structure

API keys include environment identifiers for easy recognition:

// Sandbox key
tl_dev_abc123def456gh789ijklmnopqrstuv

// Production key  
tl_live_xyz789abc123def456gh789ijklmno

Programmatic Detection

function getEnvironment(apiKey: string): 'development' | 'production' {
  if (apiKey.startsWith('tl_dev_')) return 'development';
  if (apiKey.startsWith('tl_live_')) return 'production';
  throw new Error('Invalid API key format');
}

function getBaseUrl(apiKey: string): string {
  const env = getEnvironment(apiKey);
  return env === 'development' 
    ? 'https://sandbox-api.truthlocks.com'
    : 'https://api.truthlocks.com';
}

Environment Configuration

Recommended environment variable setup for your application:

Sandbox (.env.local)

TRUTHLOCK_API_KEY=tl_dev_your_development_key
TRUTHLOCK_BASE_URL=https://sandbox-api.truthlocks.com
TRUTHLOCK_ENV=development

Production (.env.production)

TRUTHLOCK_API_KEY=tl_live_your_production_key
TRUTHLOCK_BASE_URL=https://api.truthlocks.com
TRUTHLOCK_ENV=production

Security: Never commit API keys to version control. Use secrets management (AWS Secrets Manager, HashiCorp Vault, Doppler) for production deployments.

Testing Best Practices

Integration Tests

Always run integration tests against the development environment. Never test with production credentials in CI/CD.

Mock Responses

For unit tests, use our SDK's built-in mock mode to avoid hitting the API entirely.

Data Cleanup

Sandbox data is reset weekly. Don't rely on persistent data in development for long-running tests.

Rate Limit Testing

Sandbox has generous rate limits. Ensure your app handles 429 responses gracefully for production.

Sandbox to Production

Follow this checklist when moving from development to production:

Create production API keys in console.truthlocks.com
Update environment variables with production credentials
Re-register your issuers (development issuers don't carry over)
Register production signing keys (use separate keys from development)
Request governance approval for your issuers
Configure webhook endpoints for production URLs
Set up monitoring and alerting
Test verification flow end-to-end