Secrets API

Create, reveal, rotate, and delete encrypted project secrets, and attach or detach one from a container/web/worker app over the API.

Manage encrypted project secrets over the API: store a value, read it back, rotate it, and wire it into an app as an environment variable. For the dashboard flow and product concepts (encryption, limits, pricing), see Secrets.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/secrets"

{
  "secrets": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "value_size": 0,
      "value_version": 0,
      "attachments": [
        {
          "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
          "container_name": "string",
          "env_name": "DB_PASSWORD"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "project_name": "string",
      "attachment_count": 0
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

2-63 characters: lowercase letters, digits, and hyphens, starting and ending with a letter or digit. Doubles as the Kubernetes Secret data key once attached — validated as-is, never auto-normalized.

value*string

The plaintext value. 1-65536 bytes (64 KiB). Sealed at rest; never echoed back except by POST .../reveal.

description?string

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets" \  -H "Content-Type: application/json" \  -d '{    "name": "db-password",    "value": "string"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "value_size": 0,
  "value_version": 0,
  "attachments": [
    {
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "container_name": "string",
      "env_name": "DB_PASSWORD"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets"

{
  "secrets": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "value_size": 0,
      "value_version": 0,
      "attachments": [
        {
          "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
          "container_name": "string",
          "env_name": "DB_PASSWORD"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "value_size": 0,
  "value_version": 0,
  "attachments": [
    {
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "container_name": "string",
      "env_name": "DB_PASSWORD"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

At least one of value/description is required.

value?string

New plaintext value (1-65536 bytes). Omit to leave the value untouched.

description?string

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "value_size": 0,
  "value_version": 0,
  "attachments": [
    {
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "container_name": "string",
      "env_name": "DB_PASSWORD"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08/reveal"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "value": "string"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

containerId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

secret_id*string

env_name*string

Uppercase letters, digits, and underscores, starting with a letter or underscore (e.g. DB_PASSWORD). Must not already be set on the container, reserved by the platform, or used by another secret/service-link binding.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/containers/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets" \  -H "Content-Type: application/json" \  -d '{    "secret_id": "9e739c43-5a0b-4293-91b3-7c10894ec3f4",    "env_name": "DB_PASSWORD"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "secret_id": "9e739c43-5a0b-4293-91b3-7c10894ec3f4",
  "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
  "env_name": "string",
  "created_at": "2019-08-24T14:15:22Z"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

containerId*string

secretId*string

UUID of the project secret.

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/containers/497f6eca-6276-4993-bfeb-53cbbbba6f08/secrets/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Errors use a code and a message

Every failed request returns a JSON body of the shape { "code": "...", "message": "..." }. Codes you will see on these endpoints: 401 UNAUTHORIZED; 404 NOT_FOUND (a secret, project, or app you do not own reads as not found, never leaked); 400 BAD_SECRET_NAME / 400 BAD_SECRET_VALUE (name or 64 KiB value rules), 409 SECRET_NAME_TAKEN (name already used in the project), 409 SECRET_LIMIT_REACHED (100 per project); on attach, 400 BAD_ENV_NAME, 409 ENV_NAME_TAKEN, or 409 SECRETS_TOO_LARGE (the project's attached values would exceed the total budget); 409 SECRET_IN_USE on delete while attachments exist; 409 PROJECT_SUSPENDED on write operations while the project is suspended; 503 SECRETS_UNAVAILABLE when the secrets subsystem is not available; and 502 SECRETS_SYNC_FAILED / 502 SECRET_ROTATION_NOT_APPLIED when a change was saved but could not be delivered to running apps yet — retry the call.

Values are write-only except through reveal

List and get endpoints return metadata only (name, size, version, what the secret is attached to) — never the value. The value comes back exclusively from POST .../secrets/{secretId}/reveal, and every reveal is recorded in the project's activity log.

Attach injects an environment variable

POST .../containers/{containerId}/secrets takes a secret_id and an env_name (UPPER_SNAKE_CASE, must not collide with the app's existing or platform-injected variables). The platform delivers the value to the app and restarts it, so your code simply reads the environment variable on start. DELETE .../containers/{containerId}/secrets/{secretId} removes the variable on the app's next roll.

Rotation restarts consumers

PATCH .../secrets/{secretId} with a new value bumps the secret's version and automatically restarts every app it is attached to — environment variables are read at process start, so the restart is what makes the new value take effect. A 502 SECRET_ROTATION_NOT_APPLIED response means the value was saved but a consumer could not be updated yet; retry the same call until it succeeds.

Secrets API

200application/json

401application/json

503application/json

201application/json

400application/json

401application/json

404application/json

409application/json

503application/json

200application/json

401application/json

404application/json

503application/json

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

409application/json

502application/json

503application/json

204

401application/json

404application/json

409application/json

200application/json

401application/json

404application/json

503application/json

201application/json

400application/json

401application/json

404application/json

409application/json

502application/json

503application/json

204

401application/json

404

409application/json

502application/json

503application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`