Environment variables

Values are encrypted at rest; sensitive values are never returned. See Environment variables for targets and the names the platform reserves.

GET /v1/orgs/:orgId/projects/:projectId/env

Lists the Serverless App Service's variables, and shared: the organization's shared variables (a Serverless App Service variable with the same key replaces a shared one per environment). Values of sensitive variables are null.

Auth: user access token or platform agent key · Scope: env:read

Response 200

{
  vars: {
    version: number
    access: null | {
      roles?: string[]
      teams?: string[]
    }
    rotateEveryDays: null | number
    rotationDueAt: null | number
    value: null | string
    key: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    targets: ("preview" | "production" | "development")[]
    sensitive?: boolean
    devReadable?: boolean
    updatedBy: string
    valueUpdatedAt?: number
  }[]
  shared: {
    version: number
    access: null | {
      roles?: string[]
      teams?: string[]
    }
    rotateEveryDays: null | number
    rotationDueAt: null | number
    value: null | string
    key: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    targets: ("preview" | "production" | "development")[]
    sensitive?: boolean
    devReadable?: boolean
    updatedBy: string
    valueUpdatedAt?: number
  }[]
}

Errors

GET /v1/orgs/:orgId/projects/:projectId/env/values

One environment's variables as a deployment gets them (shared ones overridden by the Serverless App Service's), for local development (si env pull, si dev). Sensitive values are null, except development-only secrets marked devReadable when the caller has env:write (audited as env.reveal).

Auth: user access token or platform agent key · Scope: env:read · Allowed: env:write

Response 200

{
  environment: "preview" | "production" | "development"
  vars: {
    key: string
    value: null | string
    sensitive: boolean
    devReadable?: true
    shared?: true
  }[]
}

Errors

POST /v1/orgs/:orgId/projects/:projectId/env

Creates or replaces many variables at once (e.g. a pasted .env file), all with the same environments and sensitivity. Nothing is written unless every key is valid.

Auth: user access token or platform agent key · Scope: env:write

Request body

Response 200

{
  keys: string[]
  targets: ("preview" | "production" | "development")[]
  sensitive: boolean
  devReadable: boolean
}

Errors

PUT /v1/orgs/:orgId/projects/:projectId/env/:key

Creates or replaces a variable. Omit value to keep the stored value, for example to change the targets of a sensitive variable.

Auth: user access token or platform agent key · Scope: env:write

Request body

Response 200

{
  key: string
  targets: ("preview" | "production" | "development")[]
  sensitive: boolean
  devReadable: boolean
  version: number
}

Errors

DELETE /v1/orgs/:orgId/projects/:projectId/env/:key

Deletes a variable. Running deployments keep the value they started with.

Auth: user access token or platform agent key · Scope: env:write

Response 204 with no body.

Errors

GET /v1/orgs/:orgId/projects/:projectId/env/:key/value

Reads a value back (version: an earlier one). Sensitive values only as their access rule allows; audited.

Auth: user access token or platform agent key · Scope: env:read · Allowed: env:write

Errors

GET /v1/orgs/:orgId/projects/:projectId/env/:key/versions

The versions kept (when each was set and by whom), newest first.

Auth: user access token or platform agent key · Scope: env:read

Response 200

{
  key: string
  current: number
  versions: {
    version: number
    createdAt?: number
    createdBy: string
    current: boolean
  }[]
}

Errors

POST /v1/orgs/:orgId/projects/:projectId/env/:key/versions/:version/restore

Sets an earlier value again, as a new version. Takes effect on the next deployment.

Auth: user access token or platform agent key · Scope: env:write

Response 200

{
  key: string
  version: number
}

Errors

PUT /v1/orgs/:orgId/projects/:projectId/env/:key/settings

A rotation reminder and who may read the value back.

Auth: user access token or platform agent key · Scopes: env:write, keys:write (when body.access !== undefined)

Request body

Response 200

{
  key: string
  rotateEveryDays: null | number
  access: null | {
    roles?: string[]
    teams?: string[]
  }
}

Errors

GET /v1/orgs/:orgId/env

Lists the organization's shared variables. Sensitive values are null.

Auth: user access token or platform agent key · Scope: env:read

Response 200

{
  vars: {
    version: number
    access: null | {
      roles?: string[]
      teams?: string[]
    }
    rotateEveryDays: null | number
    rotationDueAt: null | number
    value: null | string
    key: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    targets: ("preview" | "production" | "development")[]
    sensitive?: boolean
    devReadable?: boolean
    updatedBy: string
    valueUpdatedAt?: number
  }[]
}

POST /v1/orgs/:orgId/env

Creates or replaces many shared variables at once, all with the same environments and sensitivity.

Auth: user access token or platform agent key · Scope: env:write

Request body

Response 200

{
  keys: string[]
  targets: ("preview" | "production" | "development")[]
  sensitive: boolean
  devReadable: boolean
}

Errors

PUT /v1/orgs/:orgId/env/:key

Creates or replaces a shared variable. Omit value to keep the stored one.

Auth: user access token or platform agent key · Scope: env:write

Request body

Response 200

{
  key: string
  targets: ("preview" | "production" | "development")[]
  sensitive: boolean
  devReadable: boolean
  version: number
}

Errors

DELETE /v1/orgs/:orgId/env/:key

Deletes a shared variable. Serverless App Services' own variables with the same key are unaffected.

Auth: user access token or platform agent key · Scope: env:write

Response 204 with no body.

GET /v1/orgs/:orgId/env/:key/value

Reads a value back (version: an earlier one). Sensitive values only as their access rule allows; audited.

Auth: user access token or platform agent key · Scope: env:read · Allowed: env:write

Errors

GET /v1/orgs/:orgId/env/:key/versions

The versions kept (when each was set and by whom), newest first.

Auth: user access token or platform agent key · Scope: env:read

Response 200

{
  key: string
  current: number
  versions: {
    version: number
    createdAt?: number
    createdBy: string
    current: boolean
  }[]
}

Errors

POST /v1/orgs/:orgId/env/:key/versions/:version/restore

Sets an earlier value again, as a new version. Takes effect on the next deployment.

Auth: user access token or platform agent key · Scope: env:write

Response 200

{
  key: string
  version: number
}

Errors

PUT /v1/orgs/:orgId/env/:key/settings

A rotation reminder and who may read the value back.

Auth: user access token or platform agent key · Scopes: env:write, keys:write (when body.access !== undefined)

Request body

Response 200

{
  key: string
  rotateEveryDays: null | number
  access: null | {
    roles?: string[]
    teams?: string[]
  }
}

Errors

GET /v1/orgs/:orgId/secrets

Every secret in the organization (shared ones and each Serverless App Service's sensitive variables): key, targets, current version, last change and by whom, rotation reminder and when it's due, and the access rule. Never values. Also limit, the plan's secretsMax. Needs env:read.

Auth: user access token or platform agent key · Scope: env:read

Response 200

{
  secrets: {
    project: null | {
      projectId: string
      name: string
    }
    shared: boolean
    version: number
    access: null | {
      roles?: string[]
      teams?: string[]
    }
    rotateEveryDays: null | number
    rotationDueAt: null | number
    value: null | string
    key: string
    createdAt?: number
    updatedAt?: number
    orgId: string
    projectId: string
    targets: ("preview" | "production" | "development")[]
    sensitive?: boolean
    devReadable?: boolean
    updatedBy: string
    valueUpdatedAt?: number
  }[]
  limit: number
}