Secrets

Encrypted stack secrets management (envelope encryption via KMS)

List stack secrets

GET

/api/v1

/projects/{projectId}/stacks/{stackId}/secrets

auth_token (cookie)

Bearer

List all secrets for a stack. Masked secrets never include the value. Non-masked secrets include the decrypted value.

List stack secrets › path Parameters

projectId

string · uuid · required

Project unique identifier

stackId

string · uuid · required

Stack unique identifier

List stack secrets › Responses

List of secrets

SecretResponse[]

SecretResponse

id

string · uuid

stackId

string · uuid

key

string

value

string | null

Decrypted secret value. Null/omitted for masked secrets.

Example: my-secret-password

masked

boolean

createdAt

string · date-time

updatedAt

string · date-time

Create a stack secret

POST

/api/v1

/projects/{projectId}/stacks/{stackId}/secrets

auth_token (cookie)

Bearer

Create a new encrypted secret for a stack. If masked is true, the value can never be read back.

Create a stack secret › path Parameters

projectId

string · uuid · required

Project unique identifier

stackId

string · uuid · required

Stack unique identifier

Create a stack secret › query Parameters

override

boolean

When true, an existing key is overwritten instead of conflicting.

Default: false

Create a stack secret › Request Body

CreateSecretRequest

key

string · maxLength: 255 · required

value

string · required

masked

boolean

Example: true

Default: false

Create a stack secret › Responses

Secret successfully created

SecretResponse

id

string · uuid

stackId

string · uuid

key

string

value

string | null

Decrypted secret value. Null/omitted for masked secrets.

Example: my-secret-password

masked

boolean

createdAt

string · date-time

updatedAt

string · date-time

Create several stack secrets at once

POST

/api/v1

/projects/{projectId}/stacks/{stackId}/secrets/batch

auth_token (cookie)

Bearer

Creates up to 500 encrypted secrets for a stack in a single transaction — either all are written or none are. Values are encrypted before the transaction opens (each encryption is a KMS round-trip).

Duplicate keys inside the payload are rejected up front. A key that already exists on the stack is a conflict unless override=true, which upserts instead.

Create several stack secrets at once › path Parameters

projectId

string · uuid · required

Project unique identifier

stackId

string · uuid · required

Stack unique identifier

Create several stack secrets at once › query Parameters

override

boolean

When true, existing keys are overwritten instead of conflicting.

Default: false

Create several stack secrets at once › Request Body

CreateMultiplesSecretsRequest

CreateSecretRequest[] · minItems: 1 · maxItems: 500 · required

Secrets to create. Keys must be unique within the payload.

Create several stack secrets at once › Responses

Secrets successfully created, in payload order

SecretResponse[]

SecretResponse

id

string · uuid

stackId

string · uuid

key

string

value

string | null

Decrypted secret value. Null/omitted for masked secrets.

Example: my-secret-password

masked

boolean

createdAt

string · date-time

updatedAt

string · date-time

POST/projects/{projectId}/stacks/{stackId}/secrets/batch

curl /api/v1/projects/:projectId/stacks/:stackId/secrets/batch \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "secrets": [
    {
      "key": "DB_PASSWORD",
      "value": "my-secret-password",
      "masked": false
    }
  ]
}'

Example Request Body

{
  "secrets": [
    {
      "key": "DB_PASSWORD",
      "value": "my-secret-password",
      "masked": false
    }
  ]
}

json

Example Responses

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "stackId": "00000000-0000-0000-0000-000000000000",
    "key": "DB_PASSWORD",
    "value": "my-secret-password",
    "masked": true,
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  }
]

json

application/json

Update a stack secret

PUT

/api/v1

/projects/{projectId}/stacks/{stackId}/secrets/{secretId}

auth_token (cookie)

Bearer

Update a secret's value. The masked flag cannot be changed after creation.

Update a stack secret › path Parameters

projectId

string · uuid · required

Project unique identifier

stackId

string · uuid · required

Stack unique identifier

secretId

string · uuid · required

Secret unique identifier

Update a stack secret › Request Body

UpdateSecretRequest

value

string

Update a stack secret › Responses

Secret successfully updated

SecretResponse

id

string · uuid

stackId

string · uuid

key

string

value

string | null

Decrypted secret value. Null/omitted for masked secrets.

Example: my-secret-password

masked

boolean

createdAt

string · date-time

updatedAt

string · date-time

Delete a stack secret

DELETE

/api/v1

/projects/{projectId}/stacks/{stackId}/secrets/{secretId}

auth_token (cookie)

Bearer

Permanently delete a secret

Delete a stack secret › path Parameters

projectId

string · uuid · required

Project unique identifier

stackId

string · uuid · required

Stack unique identifier

secretId

string · uuid · required

Secret unique identifier

Delete a stack secret › Responses

Secret successfully deleted

No data returned

Stacks Ports