---
title: "Change which sandboxes get a secret, without its value."
method: PUT
path: "/v1/egress-secrets/{name}/sandboxes"
tags: ["secrets"]
---

# Change which sandboxes get a secret, without its value.

`PUT /v1/egress-secrets/{name}/sandboxes`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/egress-secrets/{name}/sandboxes`
- Auth: HTTP bearer

The body is the secret's only: labels (selectors, any one matching), sandboxes (ids) and/or apps (App or Function ids: every copy of each, of any version). {} gives it to every sandbox of the organization. A sandbox leaving the scope stops carrying the value on its next request within seconds; one entering it has it as quickly, and a new copy of a scoped App has it from its first request.

## Path parameters

- `name` string, required: The environment variable the placeholder is in, inside every sandbox of the organization. Upper case letters, digits and underscores.

## Headers

- `Idempotency-Key` string

## Request body

- object: Optional. Which sandboxes get the secret: those matching labels, those named in sandboxes, and every copy of the Apps named in apps. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before.
  - `labels` object[]: Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.
  - `sandboxes` string[]: These sandboxes (ids of this organization's sandboxes) get the secret.
  - `apps` string[]: Every copy of these Apps or Functions (their ids) gets the secret, whatever its version: copies made by later deploys, restarts and scaling too. A deploy names the secrets its copies see as environment variables (secrets on POST /v1/apps/{id}/deploys).

## Response `200`

Success

- object
  - `name` string
  - `hosts` string[]
  - `header` string
  - `format` string
  - `rules` object[]: Optional, for an account with credit. The value goes only into requests a rule allows, by method and path. A request whose path could be read two ways (an encoded slash, a semicolon, a backslash) gets no secret that has rules. Absent: every request to the hosts. Replacing a secret without rules clears them.
    - `methods` string[]: Optional. The methods allowed; every method when absent.
    - `paths` string[], required: Exact paths, or prefixes ending in /* for every path under them. Written canonically: starting with /, no . or .. segments, no ; or \, no encoded slash. An escaped character other than a letter, digit, -, ., _ or ~ matches only the same escape: a client that sends %3A needs a rule with %3A, not :.
  - `only` object: Optional. Which sandboxes get the secret: those matching labels, those named in sandboxes, and every copy of the Apps named in apps. Any other sandbox of the organization sees no placeholder and its requests never carry the value. {} gives it back to every sandbox. Absent when replacing a secret: the scope it has stays, so a new value never widens who gets it. Absent on a new secret: every sandbox, as before.
    - `labels` object[]: Sandboxes whose labels match any one of these selectors get the secret, including ones created or labelled later.
    - `sandboxes` string[]: These sandboxes (ids of this organization's sandboxes) get the secret.
    - `apps` string[]: Every copy of these Apps or Functions (their ids) gets the secret, whatever its version: copies made by later deploys, restarts and scaling too. A deploy names the secrets its copies see as environment variables (secrets on POST /v1/apps/{id}/deploys).
  - `reaches` object: Present when only is set (in GET /v1/egress-secrets): the sandboxes that get the secret now, worked out as the servers do. A label matches only sandboxes made by a key outside every compartment. Absent: every sandbox of the organization gets it.
    - `count` integer, required: How many sandboxes get it now.
    - `sandboxes` string[], required: The first 50 of their ids.
  - `placeholder` string: What the sandbox sees in the environment variable. Without header, the proxy replaces it with the value in a credential header (Authorization, x-api-key, x-goog-api-key, api-key, xi-api-key, x-subscription-token, private-token) of HTTPS requests to the hosts; in the URL or any other header it goes out as it is.
  - `valueBytes` integer
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `enforced` boolean: True when every server running the organization's sandboxes, and every server still holding an earlier version, confirmed the change; a sandbox that starts or wakes later is given it before it runs. False while a server has not confirmed it yet: each server asks Runtime for changes every 15 seconds, and one that has not heard from Runtime for a minute sends no secret's value until it has.

## Other responses

- `default`: Error

---

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