---
title: "Save a secret. The value is sealed and never returned."
method: POST
path: "/o/{org}/secrets"
tags: ["Secrets"]
---

# Save a secret. The value is sealed and never returned.

`POST /o/{org}/secrets`

## Request

- Base URL: `https://api.prix.dev`
- URL: `https://api.prix.dev/o/{org}/secrets`
- Auth: HTTP bearer

`kind: env` sets the environment variable `name` on every session that uses it; `name` follows
environment-variable rules and may not be one Rush sets itself. `kind: header` never reaches the
session's environment: E2B's egress proxy adds `header_name: header_format(value)` to the
session's HTTPS requests to each host in `targets`, outside the sandbox. `Basic {value}` takes
`username:password` and encodes it. A header secret's `name` is a label (letters, digits, `.`,
`-`, `_`). `kind: login` takes one https origin in `targets` plus `username`, `password` and an
optional base32 `totp_secret`. Its value is never in the session's environment or conversation:
the agent runs `rush-sign-in <name>` and Rush types it into the session's browser on that origin
only. The agent shares that browser, so this keeps the value out of the transcript, not out of the sandbox.
`source: onepassword` (`header` and `login` only; an environment variable is readable by the agent, so
it stays in Rush) stores no value: `value` is an `op://` reference, read with the creator's connected 1Password
service account when a session starts or signs in. A header takes one field (`op://Vault/Item/field`), a login
takes the item (`op://Vault/Item`, read as its `username`, `password` and, with `totp: true`, its one-time
code). The reference must be readable when it is saved, or the request is refused with a `SECRET_ONEPASSWORD_*` code.
`project_id` is required: the secret reaches every session in that Project.

## Request body

- object
  - `project_id` string, uuid, required: A Project of this org; every session in it gets the secret.
  - `name` string, required
  - `kind` 'env' | 'header' | 'login'
  - `value` string, required: The value; with `source: onepassword`, its `op://` reference.
  - `source` 'rush' | 'onepassword': Where the value lives. `onepassword` is for `header` and `login`.
  - `totp` boolean: `login` with `source: onepassword` only: also read the item's one-time password.
  - `description` string
  - `targets` string[]: `header` only: bare lowercase hostnames, such as `api.stripe.com` (no scheme, port, path, wildcard or IP).
  - `header_name` string: `header` only: the header to set; `Host`, `Content-Length` and hop-by-hop headers are refused.
  - `header_format` '{value}' | 'Bearer {value}' | 'Basic {value}': `header` only.
  - `username` string: `login` only.
  - `password` string: `login` only.
  - `totp_secret` string: `login` only: the base32 two-factor setup key.

## Response `201`

Saved.

- object
  - `data` Secret, required: A secret without its value.
    - `id` string, uuid, required
    - `name` string, required
    - `kind` 'env' | 'header' | 'login', required
    - `source` 'rush' | 'onepassword', required: Where the value lives; a 1Password secret holds only its reference.
    - `description` string, required
    - `project_id` string, uuid, required
    - `targets` string[], required: Hosts (header) or one origin (login); empty for env.
    - `header_name` string, nullable
    - `header_format` string, nullable
    - `has_totp` boolean, required
    - `created_by` string, uuid, nullable, required: Null once the member who added it has deleted their account; the secret stays with the Project.
    - `created_at` string, date-time, required
    - `value_updated_at` string, date-time, required
    - `last_used_at` string, date-time, nullable

## Other responses

- `409`: `SECRET_NAME_TAKEN`: a secret with this name already exists in the same scope.
- `422`: `SECRET_PROJECT_REQUIRED`, `SECRET_PROJECT_NOT_IN_ORG`, `SECRET_NAME_INVALID`, `SECRET_VALUE_INVALID`, `SECRET_KIND_INVALID`, `SECRET_SOURCE_INVALID`, `SECRET_TARGET_INVALID`, `SECRET_DESCRIPTION_INVALID`, or for a 1Password reference `SECRET_ONEPASSWORD_NOT_CONNECTED`, `SECRET_ONEPASSWORD_TOKEN_REJECTED` or `SECRET_ONEPASSWORD_NOT_FOUND` (`SECRET_ONEPASSWORD_RATE_LIMITED` is 429 and `SECRET_ONEPASSWORD_UNAVAILABLE` 502).

---

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