API

Environments

Environments represent deployment stages within an App (e.g. Development, Staging, Production). Each Environment contains its own set of Secrets. On this page, we'll look at the Environments API endpoints for listing, creating, updating, and deleting Environments.

The Environments API requires server-side encryption (SSE) to be enabled for the parent App. An app_id query parameter is required for list and create operations — omitting it returns 403 as the API cannot resolve the app context.

The Environment model

Properties

Name
id
Type
string
Description
Unique identifier for the environment.
Name
name
Type
string
Description
The name of the environment.
Name
envType
Type
string
Description
The type of environment: dev, staging, prod, or custom.
Name
index
Type
integer
Description
The display order of the environment within its app.
Name
createdAt
Type
timestamp
Description
Timestamp of when the environment was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the environment was last updated.

GET/v1/environments

List Environments

Retrieve all environments for a given app that the authenticated account has access to.

Required parameters

Name
app_id
Type
string
Description
Unique identifier for the Phase App.

Request

GET

/v1/environments

curl "https://api.phase.dev/v1/environments/?app_id=72b9ddd5-8fce-49ab-89d9-c431d53a9552" \
  -H "Authorization: Bearer {token}"

Response

[
    {
        "id": "af6b7a8e-c268-48c2-967c-032e86e26110",
        "name": "Development",
        "envType": "dev",
        "index": 0,
        "createdAt": "2024-06-01T12:00:00Z",
        "updatedAt": "2024-06-01T12:00:00Z"
    },
    {
        "id": "b12c3d4e-5678-90ab-cdef-1234567890ab",
        "name": "Staging",
        "envType": "staging",
        "index": 1,
        "createdAt": "2024-06-01T12:00:00Z",
        "updatedAt": "2024-06-01T12:00:00Z"
    },
    {
        "id": "c23d4e5f-6789-01bc-def2-3456789012cd",
        "name": "Production",
        "envType": "prod",
        "index": 2,
        "createdAt": "2024-06-01T12:00:00Z",
        "updatedAt": "2024-06-01T12:00:00Z"
    }
]

POST/v1/environments

Create Environment

Create a new environment within an app. The environment name must contain only letters, numbers, hyphens, and underscores (max 64 characters).

Required parameters

Name
app_id
Type
string
Description
Unique identifier for the Phase App.

JSON Body

Required fields

Name
name
Type
string
Description
The environment name. Must match [a-zA-Z0-9\-_]{1,64}.

Request

POST

/v1/environments

curl -X POST "https://api.phase.dev/v1/environments/?app_id=72b9ddd5-8fce-49ab-89d9-c431d53a9552" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "canary"
  }'

Response

{
    "id": "d34e5f6a-7890-12cd-ef34-567890123456",
    "name": "canary",
    "envType": "custom",
    "index": 3,
    "createdAt": "2024-06-02T10:00:00Z",
    "updatedAt": "2024-06-02T10:00:00Z"
}

GET/v1/environments/:id

Get Environment

Retrieve a single environment by its ID.

URL parameters

Name
id
Type
string
Description
The unique identifier of the environment.

Request

GET

/v1/environments/:id

curl https://api.phase.dev/v1/environments/af6b7a8e-c268-48c2-967c-032e86e26110/ \
  -H "Authorization: Bearer {token}"

Response

{
    "id": "af6b7a8e-c268-48c2-967c-032e86e26110",
    "name": "Development",
    "envType": "dev",
    "index": 0,
    "createdAt": "2024-06-01T12:00:00Z",
    "updatedAt": "2024-06-01T12:00:00Z"
}

PUT/v1/environments/:id

Update Environment

Update an environment's name.

URL parameters

Name
id
Type
string
Description
The unique identifier of the environment.

JSON Body

Name
name
Type
string
Description
The new environment name. Must match [a-zA-Z0-9\-_]{1,64}.

Request

PUT

/v1/environments/:id

curl -X PUT https://api.phase.dev/v1/environments/af6b7a8e-c268-48c2-967c-032e86e26110/ \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-v2"
  }'

Response

{
    "id": "af6b7a8e-c268-48c2-967c-032e86e26110",
    "name": "dev-v2",
    "envType": "dev",
    "index": 0,
    "createdAt": "2024-06-01T12:00:00Z",
    "updatedAt": "2024-06-02T11:00:00Z"
}

DELETE/v1/environments/:id

Delete Environment

Permanently delete an environment and all its secrets.

This action is irreversible. All secrets and access keys in the environment will be permanently deleted.

URL parameters

Name
id
Type
string
Description
The unique identifier of the environment.

Request

DELETE

/v1/environments/:id

curl -X DELETE https://api.phase.dev/v1/environments/af6b7a8e-c268-48c2-967c-032e86e26110/ \
  -H "Authorization: Bearer {token}"

Response

204 No Content