docs
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.

Note

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
{
    "data": [
        {
            "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.

Note

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