---
title: "Narrow where a secret goes, without its value."
method: PUT
path: "/v1/egress-secrets/{name}/rules"
tags: ["secrets"]
---

# Narrow where a secret goes, without its value.

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

## Request

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

Sets the secret's hosts and/or rules to ones that let the value go nowhere new: every host one of its hosts names (a.example.com or *.a.example.com under *.example.com), and every method and path a rule allows one its rules allow now (a secret without rules allows every request, so any rules narrow it). Either left out stays as it is. Anything wider is refused (400, invalid_request): a new place could learn the value, so widening needs the value (PUT /v1/egress-secrets/{name}). Recorded in the audit log as an update with narrowed. Takes effect on new connections within seconds.

## 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
  - `hosts` string[]: Where the value may go. The proxy puts it only into HTTPS requests to these hosts.
  - `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 :.

## 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)