API

Secrets

Secrets are key/value pairs used to store application secrets or environment variables for your applications. Secrets in Phase can additionally have tags and comments associated with them. On this page, we'll dive into the Secrets API and how you can use it to manage your application secrets programmatically. We'll look at how to query, create, update, and delete secrets.

To use the Secrets API to manage secrets in an App, you must enable server-side encryption (SSE) from the App settings page.

The Secret model

The secret model contains the basic key / value pairs that define your environment variable or application secret, as well as additional information such as tags, comments, personal overrides and metadata.

Properties

Name
id
Type
string
Description
Unique identifier for the secret.
Name
environment
Type
string
Description
Unique identifier for the environment in which this secret exists.
Name
key
Type
string
Description
The key of the secret, in plaintext.
Name
value
Type
string
Description
The value of the secret, in plaintext.
Name
type
Type
string
Description
The secret type. One of secret (default), sealed, or config. Sealed secrets have their values redacted in the Console UI after saving, and their type cannot be changed once saved. Config secrets are non-sensitive values displayed in plaintext by default.
Name
comment
Type
string
Description
The comment for the secret, if provided.
Name
tags
Type
array
Description
An array of tag names associated with the secret.
Name
override
Type
object
Description
A personal secret override, if set by the authenticated user making the request. Overrides are only returned when authenticating via a Personal Access Token.
Name
path
Type
string
Description
The absolute path for the secret.
Name
version
Type
number
Description
The secret version.
Name
keyDigest
Type
string
Description
The hash of the secret key.
Name
createdAt
Type
timestamp
Description
Timestamp of when the secret was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the secret was last updated.

GET/v1/secrets

Get Secrets

Retrieve all secrets in a given environment. You can optionally filter secrets by a specific path and / or secret key.

Required parameters

Name
app_id
Type
string
Description
Unique identifier for the Phase App you wish to get secrets from.
Name
env
Type
string
Description
The environment name, ex: development

Optional parameters

Name
path
Type
string
Description
Get secrets at a specific path.
Name
key
Type
string
Description
The key of a specific secret to fetch.
Name
tags
Type
string
Description
A comma separated list of tags (ex: aws, aws,postgres). Returns secrets that match ANY of the specified tags.
Name
dynamic
Type
boolean
Description
Whether to include dynamic secrets in the response.
Name
lease
Type
boolean
Description
Whether to generate leases for dynamic secrets in the response. Must be used along with the dynamic parameter.
Name
lease_ttl
Type
boolean
Description
The TTL to use when generating leases for dynamic secrets, in seconds. Must be used along with the lease parameter.

Request

GET

/v1/secrets

curl -G https://api.phase.dev/v1/secrets/ \
  -H "Authorization: Bearer {token}" \
  -d app_id=72b9ddd5-8fce-49ab-89d9-c431d53a9552 \
  -d env=development \
  -d path=/backend \
  -d key=DEBUG \
  -d tags=aws,postgres

Response

[
    {
        "id": "36fc2244-47f5-4ff4-8b72-deed1bf876da",
        "key": "DEBUG",
        "value": "False",
        "type": "secret",
        "comment": "Debug mode for the backend app",
        "tags": ["config"],
        "override": {
            "id": "904a64c7-95df-470f-aa58-6beaa55dea3c",
            "value": "True",
            "isActive": true,
            "createdAt": "2024-04-11T15:03:02.029689Z",
            "updatedAt": "2024-04-11T15:03:02.032630Z"
        },
        "path": "/backend",
        "keyDigest": "2bba3630bec4829f3f98b9fd7548e4f782df43a24ba5d94c2dd80e1fe618c65e",
        "version": 2,
        "createdAt": "2024-02-13T13:41:45.551255Z",
        "updatedAt": "2024-02-14T07:44:10.926591Z",
        "environment": "af6b7a8e-c268-48c2-967c-032e86e26110",
    }
]

POST/v1/secrets

Create Secrets

Create one or more secrets in a specific environment. You can optionally supply a path, comment and tags for the secret.

Required parameters

Name
app_id
Type
string
Description
Unique identifier for the Phase App.
Name
env
Type
string
Description
The environment name, ex: development

JSON Body

Secret data must be supplied in the JSON request body as an array in the secrets field. Each secret must have a key and value, and you can optionally add a comment, list of tags and a specified path. You can add multiple secrets in the secrets array to create multiple secrets in a single request.

Required fields

Name
key
Type
string
Description
The secret key.
Name
value
Type
string
Description
The secret value.

Optional fields

Name
type
Type
string
Description
The secret type. One of secret, sealed, or config. Defaults to secret.
Name
comment
Type
string
Description
A comment to associate with the secret.
Name
tags
Type
array
Description
A list of tags to associate with the secret. Tag names must be valid.
Name
path
Type
string
Description
The path at which to create this secret. Defaults to / if not provided.
Name
override
Type
object
Description
A personal secret override to be used in place of the default value. The override must be suppled with fields value and isActive

Request

POST

/v1/secrets

curl --location 'https://api.phase.dev/v1/secrets/?app_id=72b9ddd5-8fce-49ab-89d9-c431d53a9552&env=development' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
    "secrets": [
        {
            "key": "DB_NAME",
            "value": "postgres",
            "comment": "primary db name",
            "tags": ["db"],
            "path": "/backend",
            "override": {
                "value": "postgres-dev",
                "isActive": true
            }
        }
    ]
}'

Response

[
    {
        "id": "36fc2244-47f5-4ff4-8b72-deed1bf876da",
        "key": "DB_NAME",
        "value": "postgres",
        "type": "secret",
        "comment": "primary db name",
        "tags": ["db"],
        "path": "/backend",
        "override": {
            "id": "904a64c7-95df-470f-aa58-6beaa55dea3c",
            "value": "postgres-dev",
            "isActive": true,
            "createdAt": "2024-04-11T15:03:02.029689Z",
            "updatedAt": "2024-04-11T15:03:02.032630Z"
        },
        "keyDigest": "2bba3630bec4829f3f98b9fd7548e4f782df43a24ba5d94c2dd80e1fe618c65e",
        "version": 1,
        "createdAt": "2024-02-13T13:41:45.551255Z",
        "updatedAt": "2024-02-14T07:44:10.926591Z",
        "environment": "af6b7a8e-c268-48c2-967c-032e86e26110",
    }
]

PUT/v1/secrets

Update Secrets

Update one or more secrets in an environment.

Required parameters

Name
app_id
Type
string
Description
Unique identifier for the Phase App.
Name
env
Type
string
Description
The environment name, ex: development

JSON Body

Secret data must be supplied in the JSON request body as an array in the secrets field. You must supply an id for each secret you want to update. Optionally you can supply the specific fields you wish to update for this secret. You can add multiple secrets in the secrets array to update multiple secrets in a single request.

Required fields

Name
id
Type
string
Description
Unique identifier for the Secret.

Optional fields

Name
key
Type
string
Description
The secret key.
Name
value
Type
string
Description
The secret value.
Name
type
Type
string
Description
The secret type. One of secret, sealed, or config. Note: sealed secrets cannot have their type changed.
Name
comment
Type
string
Description
A comment to associate with the secret.
Name
tags
Type
array
Description
A list of tags to associate with the secret. Tag names must be valid. The supplied list will overwrite any existing tags.
Name
path
Type
string
Description
The path for this secret.
Name
override
Type
object
Description
A personal secret override to be used in place of the default value. The override must be suppled with fields value and isActive

Request

PUT

/v1/secrets

curl --location --request PUT 'https://api.phase.dev/v1/secrets/?app_id=72b9ddd5-8fce-49ab-89d9-c431d53a9552&env=development' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
    "secrets": [
        {
            "id": "f8621d1a-6903-4b60-8e8d-2085a2475871",
            "key": "DB_NAME_POSTGRES",
            "value": "postgres-primary",
            "comment": "primary db name",
            "path": "/backend/db",
            "override": {
                "value": "postgres-dev",
                "isActive": true
            }
        }
    ]
}'

Response

[
    {
        "id": "36fc2244-47f5-4ff4-8b72-deed1bf876da",
        "key": "DB_NAME_POSTGRES",
        "value": "postgres-primary",
        "type": "secret",
        "comment": "primary db name",
        "tags": ["db"],
        "path": "/backend/db",
        "override": {
            "id": "904a64c7-95df-470f-aa58-6beaa55dea3c",
            "value": "postgres-dev",
            "isActive": true,
            "createdAt": "2024-04-11T15:03:02.029689Z",
            "updatedAt": "2024-04-11T15:05:026.032630Z"
        },
        "keyDigest": "2bba3630bec4829f3f98b9fd7548e4f782df43a24ba5d94c2dd80e1fe618c65e",
        "version": 2,
        "createdAt": "2024-02-13T13:41:45.551255Z",
        "updatedAt": "2024-02-14T07:44:10.926591Z",
        "environment": "af6b7a8e-c268-48c2-967c-032e86e26110",
    }
]

DELETE/v1/secrets

Delete Secrets

Delete one or more secrets from an environment.

Required parameters

Name
app_id
Type
string
Description
Unique identifier for the Phase App you wish to delete secrets from.
Name
env
Type
string
Description
The environment name, ex: development

JSON Body

Data must be supplied in the JSON request body as an array in the secrets field. You must supply an id for each secret you want to delete.

Required fields

Name
id
Type
string
Description
Unique identifier for the secret.

Request

DELETE

/v1/secrets

curl --location --request DELETE 'https://api.phase.dev/v1/secrets/?app_id=72b9ddd5-8fce-49ab-89d9-c431d53a9552&env=development' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data '{
    "secrets": ["fad9b534-792a-425b-bfa6-00c26a60f36d"]
}'

Response

{
    "message": "Deleted 1 secret"
}