API

Apps

Apps are the top-level organizational unit in Phase. Each App contains Environments, which in turn hold Secrets. On this page, we'll look at the Apps API endpoints for listing, creating, updating, and deleting Apps.

The Apps API requires server-side encryption (SSE). Apps created via the API are SSE-enabled by default. Only SSE-enabled Apps are returned by the API.

The App model

Properties

Name
id
Type
string
Description
Unique identifier for the app.
Name
name
Type
string
Description
The name of the app.
Name
description
Type
string
Description
An optional description for the app.
Name
sseEnabled
Type
boolean
Description
Whether server-side encryption is enabled for this app.
Name
createdAt
Type
timestamp
Description
Timestamp of when the app was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the app was last updated.

GET/v1/apps

List Apps

Retrieve all SSE-enabled apps that the authenticated account has access to.

Request

GET

/v1/apps

curl https://api.phase.dev/v1/apps/ \
  -H "Authorization: Bearer {token}"

Response

[
    {
        "id": "58006442-007b-4625-b8e2-80f7606484a0",
        "name": "My App",
        "description": "Production application",
        "sseEnabled": true,
        "createdAt": "2024-06-01T12:00:00Z",
        "updatedAt": "2024-06-01T12:00:00Z"
    }
]

POST/v1/apps

Create App

Create a new SSE-enabled App. By default, three environments are created automatically: Development, Staging, and Production. You can optionally supply a custom list of environment names.

JSON Body

Required fields

Name
name
Type
string
Description
The app name. Maximum 64 characters.

Optional fields

Name
description
Type
string
Description
A description for the app. Maximum 10,000 characters.
Name
environments
Type
array
Description
A list of custom environment names to create instead of the defaults. Each name must contain only letters, numbers, hyphens, and underscores. Requires a paid plan.

Request

POST

/v1/apps

curl -X POST https://api.phase.dev/v1/apps/ \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New App",
    "description": "A new application"
  }'

Response

{
    "id": "72b9ddd5-8fce-49ab-89d9-c431d53a9552",
    "name": "My New App",
    "description": "A new application",
    "sseEnabled": true,
    "createdAt": "2024-06-01T12:00:00Z",
    "updatedAt": "2024-06-01T12:00:00Z"
}

GET/v1/apps/:id

Get App

Retrieve a single app by its ID.

URL parameters

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

Request

GET

/v1/apps/:id

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

Response

{
    "id": "72b9ddd5-8fce-49ab-89d9-c431d53a9552",
    "name": "My App",
    "description": "Production application",
    "sseEnabled": true,
    "createdAt": "2024-06-01T12:00:00Z",
    "updatedAt": "2024-06-01T12:00:00Z"
}

PUT/v1/apps/:id

Update App

Update an app's name and/or description. At least one field must be provided.

URL parameters

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

JSON Body

Name
name
Type
string
Description
The new app name. Maximum 64 characters.
Name
description
Type
string
Description
The new app description. Maximum 10,000 characters.

Request

PUT

/v1/apps/:id

curl -X PUT https://api.phase.dev/v1/apps/72b9ddd5-8fce-49ab-89d9-c431d53a9552/ \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated App Name",
    "description": "Updated description"
  }'

Response

{
    "id": "72b9ddd5-8fce-49ab-89d9-c431d53a9552",
    "name": "Updated App Name",
    "description": "Updated description",
    "sseEnabled": true,
    "createdAt": "2024-06-01T12:00:00Z",
    "updatedAt": "2024-06-02T10:30:00Z"
}

DELETE/v1/apps/:id

Delete App

Permanently delete an app and all its associated data.

This action is irreversible. All environments, secrets, and access configurations associated with the app will be permanently deleted.

URL parameters

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

Request

DELETE

/v1/apps/:id

curl -X DELETE https://api.phase.dev/v1/apps/72b9ddd5-8fce-49ab-89d9-c431d53a9552/ \
  -H "Authorization: Bearer {token}"

Response

204 No Content