Environments

Environments can also be managed in the KeyStone Dashboard under Settings > Environments - no code required.

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

const env = await client.environments.create({
  name: "Staging",
  slug: "staging",
  type: "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)
`type`	`string`	Yes	-	`development`, `staging`, or `production`
`auth0ClientId`	`string`	Yes	-	M2M client ID for this environment
`defaultTimeoutSeconds`	`number`	No	`3600`	Default settlement timeout (60 to 604800)

Any other key is rejected with 422. Webhook delivery is configured per endpoint under webhooks, not on the environment.

auth0ClientId must be an M2M application your Keystone operator has already created and authorized against the Keystone API. Keystone verifies this before saving the environment: a client id that is not authorized for the Keystone API (including a client id that does not exist, or one belonging to a different API) is rejected with 422 UNRECOGNIZED_CLIENT, and an empty value is rejected as a validation error. The same check runs on secret rotation.

list / get

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
`type`	`string`	`development`, `staging`, or `production`
`auth0ClientId`	`string`	M2M credential for this environment
`apiVersion`	`string \| null`	Pinned API version
`defaultTimeoutSeconds`	`number`	Default settlement timeout
`isActive`	`boolean`	Whether M2M auth is accepted (read-only)
`rateLimitRpm`	`number \| null`	Operator-granted limit, `null` means the default (read-only)
`createdAt`	`string`	Creation timestamp
`updatedAt`	`string`	Last update timestamp

update

await client.environments.update("env-uuid", {
  defaultTimeoutSeconds: 7200,
});

Field	Type	Description
`name`	`string`	Display name
`defaultTimeoutSeconds`	`number`	Settlement timeout

These two fields are the whole update surface; any other key is rejected with 422 rather than silently ignored. isActive is changed through deactivate below, and rateLimitRpm is set by your Keystone operator.

deactivate

Deactivate an environment. Preserves all data but blocks M2M authentication using this environment’s credentials once the deactivation commits.

const env = await client.environments.deactivate("env-uuid");
console.log(env.isActive); // false

Deactivation closes the environment to new settlements: resting instructions no longer match, and no repo closing settlement is derived while it is inactive. It does not stop settlements already in flight - they keep advancing to completion, and their webhooks keep delivering. This is the only way to deactivate an environment, and it is one-way. Reactivation is performed by a Keystone operator on request: the environment’s own credentials stop authenticating once the deactivation commits, so no call you can make would reach it.

Overview

Backend SDKs

Frontend Library

Tools

create

list / get

EnvironmentRead

update

deactivate

​create

​list / get

​EnvironmentRead

​update

​deactivate

create

list / get

EnvironmentRead

update

deactivate