Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

Truthlocks provides multiple environments so you can develop, test, and ship with confidence. Every tenant starts with a production environment and a shared sandbox. You can also create dedicated development and staging environments within your tenant for complete data isolation.

​
Base URLs

EnvironmentAPI Base URLConsole URL
Sandboxhttps://sandbox-api.truthlocks.comhttps://console.truthlocks.com
Productionhttps://api.truthlocks.comhttps://console.truthlocks.com
API keys are environment-specific. A development API key (prefix tl_dev_) will not work in production, and vice versa.

​
Try it in the API playground

Every API reference endpoint includes an interactive playground where you can build and send requests directly from the docs. Use the environment switcher at the top of the playground to toggle between Production (api.truthlocks.com) and Sandbox (sandbox-api.truthlocks.com). The playground covers the full API surface, including all 44 Machine Identity (MAIP) endpoints — agent registration, session management, trust scores, orchestrations, guardrails, and more. MAIP endpoints support both X-API-Key and Bearer JWT authentication in the playground. Sandbox requests use isolated test data, so you can experiment without affecting production. Enter your API key, fill in parameters, and click Send to see a live response.
Start in the Sandbox to explore endpoints risk-free, then switch to Production when you’re ready to go live.

​
Sandbox vs production

FeatureSandboxProduction
API Key Prefixtl_dev_tl_live_
Issuer Auto-ApprovalIssuers are auto-approvedRequires governance approval
Rate Limits1,000 req/minBased on tier (60-unlimited)
Daily Quota10,000 attestationsBased on tier
Data Retention30 daysPermanent
SLABest effort99.9% uptime
Transparency LogEphemeral (reset weekly)Permanent, append-only

​
Tenant environments

In addition to the shared sandbox, each tenant can create dedicated DEV and STAGING environments. These provide full data isolation at the database level using row-level security, so data created in one environment is invisible to another.
KindPurposeCreated automatically
PRODLive production dataYes
STAGINGPre-production testingNo
DEVDevelopment and experimentationNo
Use tenant environments when you need to:
  • Test minting and verification flows without affecting production data
  • Run integration tests against a dedicated environment with its own API keys
  • Stage changes before promoting them to production

​
Creating an environment

Create a DEV or STAGING environment from the console at Settings > Environments, or via the API: 
curl -X POST https://api.truthlocks.com/v1/environments \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development",
    "slug": "dev",
    "kind": "DEV"
  }'

{
  "id": "env_abc123",
  "tenant_id": "t_xyz789",
  "name": "Development",
  "slug": "dev",
  "kind": "DEV",
  "status": "ACTIVE",
  "created_at": "2026-03-28T10:00:00Z"
}
You can create one environment per kind. The PROD environment is created automatically and cannot be created or deleted through the API.

​
Listing environments

curl https://api.truthlocks.com/v1/environments \
  -H "X-API-Key: tl_live_..."

​
Switching environments

Activate a different environment for your current session: 
curl -X POST https://api.truthlocks.com/v1/environments/{id}/activate \
  -H "X-API-Key: tl_live_..."
The response includes the active environment context: 
{
  "status": "activated",
  "environment_id": "env_abc123",
  "environment_kind": "DEV",
  "environment_slug": "dev"
}
After activation, subsequent API requests in the same session are scoped to the selected environment. In the console, use the environment switcher in the top navigation bar to change environments. The switcher displays your active environment with a color-coded label — blue for sandbox and orange for production. Click it to open a dropdown listing all available environments, then select the one you want to activate. Switching to production requires a confirmation prompt to prevent accidental changes to live data. When you confirm, the page reloads with the new environment context applied to all subsequent actions.
Non-production environments (DEV and STAGING) display a floating badge in the bottom-right corner of the console as a visual reminder that you are not working with live data.

​
How isolation works

Every tenant-scoped API request requires a valid environment context. The environment is determined automatically from your API key or session token — it cannot be overridden via request headers. If the environment context is missing or invalid, the API returns 401 or 403. This fail-closed behavior ensures that a DEV API key can never access production data, even if a request is accidentally routed to the wrong environment.

​
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:
1

Create Keys

Create production API keys in console.truthlocks.com
2

Update Config

Update environment variables with production credentials
3

Re-Register

Re-register your issuers (development issuers don’t carry over)
4

Register Signing Keys

Register production signing keys (use separate keys from development)
5

Request Approval

Request governance approval for your issuers
6

Setup Webhooks

Configure webhook endpoints for production URLs
7

Monitoring

Set up monitoring and alerting
8

Test E2E

Test verification flow end-to-end

​
Next Steps

Authentication

Learn how to authenticate API requests securely.

Rate Limits

Understand quotas and how to handle rate limiting.