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

# Environments

> Manage platform environments for data isolation.

<Info>
  Environments can also be managed in the [KeyStone Dashboard](https://app.keystoneos.xyz) under **Settings > Environments** - no code required.
</Info>

Environments provide data isolation within a platform (e.g., development, staging, production). Each environment has its own settlements, webhooks, IP allowlists, and M2M credentials.

## create

```typescript theme={null}
const env = await client.environments.create({
  name: "Staging",
  slug: "staging",
  auth0ClientId: "your-staging-m2m-client-id",
  defaultTimeoutSeconds: 3600,
});
```

| Field                   | Type     | Required | Default | Description                                  |
| ----------------------- | -------- | -------- | ------- | -------------------------------------------- |
| `name`                  | `string` | Yes      | -       | Display name                                 |
| `slug`                  | `string` | Yes      | -       | URL-friendly identifier (lowercase, hyphens) |
| `auth0ClientId`         | `string` | Yes      | -       | M2M client ID for this environment           |
| `webhookUrl`            | `string` | No       | -       | Default webhook URL                          |
| `webhookSecret`         | `string` | No       | -       | Default webhook secret                       |
| `defaultTimeoutSeconds` | `number` | No       | `3600`  | Default settlement timeout (60 to 604800)    |

***

## list / get

```typescript theme={null}
const { items } = await client.environments.list();

const env = await client.environments.get("env-uuid");
console.log(`${env.name} (${env.slug}): active=${env.isActive}`);
```

### EnvironmentRead

| Field                   | Type             | Description                               |
| ----------------------- | ---------------- | ----------------------------------------- |
| `id`                    | `string`         | Environment UUID                          |
| `platformId`            | `string`         | Parent platform UUID                      |
| `name`                  | `string`         | Display name                              |
| `slug`                  | `string`         | URL-friendly identifier                   |
| `auth0ClientId`         | `string`         | M2M credential for this environment       |
| `webhookUrl`            | `string \| null` | Default webhook URL                       |
| `apiVersion`            | `string \| null` | Pinned API version                        |
| `defaultTimeoutSeconds` | `number`         | Default settlement timeout                |
| `isActive`              | `boolean`        | Whether M2M auth is accepted              |
| `rateLimitRpm`          | `number \| null` | Rate limit override (requests per minute) |
| `createdAt`             | `string`         | Creation timestamp                        |
| `updatedAt`             | `string`         | Last update timestamp                     |

***

## update

```typescript theme={null}
await client.environments.update("env-uuid", {
  defaultTimeoutSeconds: 7200,
  rateLimitRpm: 1000,
});
```

| Field                   | Type             | Description            |
| ----------------------- | ---------------- | ---------------------- |
| `name`                  | `string`         | Display name           |
| `webhookUrl`            | `string \| null` | Default webhook URL    |
| `webhookSecret`         | `string \| null` | Default webhook secret |
| `defaultTimeoutSeconds` | `number`         | Settlement timeout     |
| `isActive`              | `boolean`        | Enable or disable      |
| `rateLimitRpm`          | `number \| null` | Rate limit override    |

***

## deactivate

Deactivate an environment. Preserves all data but blocks M2M authentication using this environment's credentials.

```typescript theme={null}
const env = await client.environments.deactivate("env-uuid");
console.log(env.isActive); // false
```

To reactivate, use `update` with `isActive: true`.