> ## 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.

# Environments

> Manage sandbox, development, staging, and production environments for safe integration and testing.

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

| 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` |

<Warning>
  API keys are environment-specific. A development API key
  (prefix `tl_dev_`) will not work in production, and vice versa.
</Warning>

## Try it in the API playground

Every [API reference](/api-reference/attestations/mint) 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)](/guides/machine-identity) 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.

<Tip>
  Start in the Sandbox to explore endpoints risk-free, then switch to Production when you're ready to go live.
</Tip>

## Sandbox vs production

| 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       |

## 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.

| Kind        | Purpose                         | Created automatically |
| ----------- | ------------------------------- | --------------------- |
| **PROD**    | Live production data            | Yes                   |
| **STAGING** | Pre-production testing          | No                    |
| **DEV**     | Development and experimentation | No                    |

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:

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
curl https://api.truthlocks.com/v1/environments \
  -H "X-API-Key: tl_live_..."
```

### Switching environments

Activate a different environment for your current session:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/environments/{id}/activate \
  -H "X-API-Key: tl_live_..."
```

The response includes the active environment context:

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

### 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:

```text theme={null}
// Sandbox key
tl_dev_abc123def456gh789ijklmnopqrstuv

// Production key
tl_live_xyz789abc123def456gh789ijklmno
```

### Programmatic Detection

```javascript theme={null}
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)

```text theme={null}
TRUTHLOCK_API_KEY=tl_dev_your_development_key
TRUTHLOCK_BASE_URL=https://sandbox-api.truthlocks.com
TRUTHLOCK_ENV=development
```

### Production (.env.production)

```text theme={null}
TRUTHLOCK_API_KEY=tl_live_your_production_key
TRUTHLOCK_BASE_URL=https://api.truthlocks.com
TRUTHLOCK_ENV=production
```

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

## Testing Best Practices

<CardGroup cols={2}>
  <Card title="Integration Tests">
    Always run integration tests against the development environment. Never test
    with production credentials in CI/CD.
  </Card>

  <Card title="Mock Responses">
    For unit tests, use our SDK's built-in mock mode to avoid hitting the API
    entirely.
  </Card>

  <Card title="Data Cleanup">
    Sandbox data is reset weekly. Don't rely on persistent data in development
    for long-running tests.
  </Card>

  <Card title="Rate Limit Testing">
    Sandbox has generous rate limits. Ensure your app handles 429 responses
    gracefully for production.
  </Card>
</CardGroup>

## Sandbox to Production

Follow this checklist when moving from development to production:

<Steps>
  <Step title="Create Keys">
    Create production API keys in
    [console.truthlocks.com](https://console.truthlocks.com)
  </Step>

  <Step title="Update Config">
    Update environment variables with production credentials
  </Step>

  <Step title="Re-Register">
    Re-register your issuers (development issuers don't carry over)
  </Step>

  <Step title="Register Signing Keys">
    Register production signing keys (use separate keys from development)
  </Step>

  <Step title="Request Approval">
    Request governance approval for your issuers
  </Step>

  <Step title="Setup Webhooks">
    Configure webhook endpoints for production URLs
  </Step>

  <Step title="Monitoring">Set up monitoring and alerting</Step>
  <Step title="Test E2E">Test verification flow end-to-end</Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield-check" href="/security/auth">
    Learn how to authenticate API requests securely.
  </Card>

  <Card title="Rate Limits" icon="gauge-simple-high" href="/ops/limits">
    Understand quotas and how to handle rate limiting.
  </Card>
</CardGroup>