> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> Understand Essal's sandbox, staging, and production environments and how to configure each.

Essal provides three isolated environments per workspace. Each environment has its own base URL, API keys, data store, and configuration — changes in one environment do not affect another.

## Environment Overview

| Environment    | Base URL                             | Purpose                                          |
| -------------- | ------------------------------------ | ------------------------------------------------ |
| **Production** | `https://api.essal.cloud/v1`         | Live data and real user interactions             |
| **Staging**    | `https://staging.api.essal.cloud/v1` | Pre-release testing; mirrors production config   |
| **Sandbox**    | `https://sandbox.essal.cloud/v1`     | Safe experimentation; data resets every 24 hours |

## Sandbox

The sandbox is a fully functional replica of the production API. It is ideal for initial integration work and automated testing.

Key behaviours:

* All write operations succeed and return realistic mock IDs
* Webhook events fire against your configured sandbox endpoint
* Data is wiped and reset daily at `00:00 UTC`
* No real emails, notifications, or external calls are triggered

```bash theme={null}
# Target the sandbox with your sandbox API key
curl -X GET https://sandbox.essal.cloud/v1/office/documents \
  -H "X-API-Key: esk_sandbox_xxxxxxxxxxxxxxxxxxxx"
```

<Note>
  Sandbox API keys are prefixed with `esk_sandbox_`. They cannot be used against the production or staging endpoints.
</Note>

## Staging

Staging is a persistent environment intended for integration testing and UAT. Unlike the sandbox, data is retained across sessions and can be seeded with representative fixtures.

Staging mirrors your production environment's app configuration, permission policies, and webhook subscriptions, making it the safest environment to validate releases before deployment.

## Production

Production is your live environment. API keys prefixed with `esk_live_` are scoped to production. All actions taken against the production API affect real workspace data.

<Warning>
  Always validate changes in sandbox or staging before targeting production. Destructive API calls (e.g. `DELETE`) in production cannot be undone through the API.
</Warning>

## Switching Environments

Set the target environment using the appropriate base URL and API key. Most Essal SDKs accept an `environment` configuration option:

```js theme={null}
import { EssalClient } from "@essal/sdk";

const client = new EssalClient({
  apiKey: process.env.ESSAL_API_KEY,
  environment: "sandbox", // "production" | "staging" | "sandbox"
});
```

## Per-App Environment Variables

Each app within a workspace can have environment-specific overrides, such as different webhook endpoints or storage buckets. Configure these in **Settings → Environments** within the admin dashboard.