Skip to main content
An environment is a boundary inside an organization that holds tenants and API keys. Use separate environments to keep dev, staging, and production data — and their keys — apart. Environment administration is a dashboard operation, so every endpoint here requires a user session.
All endpoints on this page are [User] — they require a signed-in user session and are not available to API keys.
An API key is bound to a single environment and can never reach another. Create at least one key per environment you run against. See Authentication.

​
Endpoints

​
List environments

GET /environments Lists the environments in an organization, each with a count of the tenants it contains.
​
string
required
The organization whose environments to list.

​
Create an environment

POST /environments Creates a new environment in an organization.
​
string
required
The organization to create the environment in.
​
string
required
Display name for the environment.
​
string
required
Environment type — one of dev, staging, production, custom, or personal. The type determines the prefix of keys created in it (sk_live_ for production/personal, sk_test_ otherwise).
Only administrative roles (owner, billing_admin) may create environments.

​
Get an environment

GET /environments/:id Returns a single environment, including counts of the tenants and API keys it contains.
​
string
required
The environment ID.

​
Update an environment

PATCH /environments/:id Updates any supplied mutable field.
​
string
required
The environment ID.
​
string
New display name.
​
string
New environment type — dev, staging, production, custom, or personal. Future keys created in the environment use the prefix associated with this type.
​
string
active or inactive.
Only administrative roles may update an environment.

​
Delete an environment

DELETE /environments/:id Permanently deletes an environment and the tenants, keys, and content within it.
​
string
required
The environment ID.
Only the owner may delete an environment. This is irreversible.

​
Next steps

Tenancy

See how environments, tenants, and keys fit together.

Tenants

Provision tenants inside an environment.

API keys

Create keys scoped to this environment.