---
title: "Replace the secret names bound to a workspace"
method: PUT
path: "/v1/workspaces/{workspace_id}/secrets"
tags: ["Workspaces"]
---

# Replace the secret names bound to a workspace

`PUT /v1/workspaces/{workspace_id}/secrets`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/workspaces/{workspace_id}/secrets`
- Auth: HTTP bearer

Replaces the whole binding (`names: []` clears it); applies from the next exec/PTY start (running processes keep their environment). Every name must be a live secret this workspace may use (its project, its id, and allowed_tools including exec and pty), else 422 details.reason secret_not_available with details.names and nothing changes. A name equal to a key of the template version’s env or one of its text inputs is 422 env_collision (details.name;). Exactly the given names are bound (the version’s secret inputs join the binding only through open). Audited when the binding changes. 409 workspace_deleted.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- object
  - `names` string[], required: Secret names bound to the workspace (max 50, unique): injected as environment variables into every exec and PTY start (terminal sessions included), together with the call’s own `secret_refs`. Each must name a live secret this workspace may use (its project, its id, and allowed_tools including exec and pty), else 422 details.reason secret_not_available with details.names.

## Response `200`

Secret names bound to a workspace and their current status. Never values.

- object: Secret names bound to a workspace and their current status. Never values.
  - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `names` string[], required: The bound names, in the order they were given.
  - `secrets` object[], required
    - `name` string, required
    - `status` union, required: available: injected at the next exec/PTY start. not_allowed: a live secret exists but its permissions no longer allow this workspace (project, workspace id, or exec+pty); exec/PTY starts are refused with 403 secret_not_available until fixed. deleted: no live secret of this name is visible to the workspace.
      - 'available'
      - 'not_allowed'
      - 'deleted'
    - `secret_id` string, uuid, nullable, required: UUIDv7, lowercase canonical form.
    - `scope` union, required
      - 'organization'
      - 'project'

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)