Secrets API

PUT /v1/secrets/{owner}/{name}

Stores name for the owner and replaces an existing value. A new value reaches environment services by a rolling restart, and a workspace, sandbox or session on its next start.

name is in the path: A-Z, 0-9 and _, not starting with a digit, so DB_URL.

{ "value": "postgres://app:s3cret@db:5432/app" }

Response: 204, empty.

Errors:

• 403 — only a team admin can change team secrets (a member who is not an admin); paused or removed, as above.
• 404 — not found: the owner is a team you are not in, or not a valid owner.
• 409 — secrets: 100 of 100 in use when the name is new and the owner already holds 100; secrets are being changed; try again when concurrent writes kept winning three times in a row.
• 422 — `db-url` is not a secret name: use A-Z, 0-9 and _, not starting with a digit; a secret value is at most 64 KiB.

DELETE /v1/secrets/{owner}/{name}

Deletes one secret. Refused while a workspace, sandbox, environment service or pipeline of the owner references it. A pipeline counts when its newest version names the secret, or a queued or running run took it.

Response: 204, empty.

Errors:

• 403, 404 as for PUT; 404 not found also when name is not a valid secret name or the owner has no secret of that name.
• 409 — DB_URL is referenced by environment dev service api, workspace api (the referrers, sorted, comma separated: workspace {name}, sandbox {id}, environment {name} service {service}, pipeline {name}, pipeline run {name} #{number}); secrets are being changed; try again.

GET /v1/secrets/{owner}

The names the owner holds, with when and by whom each was last set, sorted by name. Never a value. [] when there are none.

Response: 200

[  { "name": "DB_URL", "updated_at": "2026-10-17T09:30:00Z", "updated_by": "karthik" },  { "name": "TOKEN", "updated_at": "2026-10-16T14:02:11Z", "updated_by": "asha" }]

Errors:

• 403 — paused or removed, as above.
• 404 — not found: the owner is a team you are not in, another person, or not a valid owner.

PUT /v1/secrets/{owner}/mine/{name}

Stores the caller's own name in the team {owner} and replaces an existing value. Any active member of the team, whatever the role. The member is always the caller, so no route writes another person's secret. The caller's workspaces, benches and sandboxes in the team take this value over the team's value of the same name. Environment services and pipeline jobs never read it. A new value reaches a workspace on its next start.

The body and limits are those of PUT /v1/secrets/{owner}/{name}; the 100 names count per member in each team.

{ "value": "ghp_example" }

Response: 204, empty.

Errors:

• 403 — your access to {team} is paused.
• 404 — not found: a team you are not in or have left, an unknown team, another person's handle, or an {owner} that is not a valid handle.
• 409 — secrets: 100 of 100 in use; secrets are being changed; try again.
• 422 — `db-url` is not a secret name: use A-Z, 0-9 and _, not starting with a digit; a secret value is at most 64 KiB.

DELETE /v1/secrets/{owner}/mine/{name}

Deletes the caller's own name in the team {owner}. Refused while one of the caller's workspaces or sandboxes in the team references the name and the team holds no secret of that name. When the team holds it, the delete goes through and the reference resolves to the team's value.

Response: 204, empty.

Errors:

• 403, 404 as for PUT /v1/secrets/{owner}/mine/{name}; 404 not found also when name is not a valid secret name or the caller holds no secret of that name.
• 409 — GITHUB_TOKEN is referenced by workspace api (only the caller's own referrers in the team: workspace {name}, sandbox {id}); secrets are being changed; try again.

GET /v1/secrets/{owner}/mine

The names the caller holds in the team {owner}, in the shape of GET /v1/secrets/{owner}, sorted by name. Never a value. [] when there are none. No route lists another member's names, for an admin or a superadmin either.

Response: 200

[  { "name": "GITHUB_TOKEN", "updated_at": "2026-10-20T08:10:00Z", "updated_by": "karthik" }]

Errors:

• 403, 404 as for PUT /v1/secrets/{owner}/mine/{name}.

A reference in a member's own workspace, bench or sandbox in a team resolves to the member's value first, then the team's. When neither holds the name, the save is 422 `NAME` is not a secret of {team} or yours.