---
title: "Set a workspace secret"
method: POST
path: "/sandboxes/secrets"
tags: ["Sandboxes"]
---

# Set a workspace secret

`POST /sandboxes/secrets`

## Request

- Base URL: `https://api.hedra.com/v3`
- URL: `https://api.hedra.com/v3/sandboxes/secrets`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Store a secret that any member's sandbox can name in `secrets`: 201
for a new name, 200 when it replaces the value of a name your workspace
holds. Only a workspace owner or admin can set one.

## Request body

- SetSandboxSecretRequest: A workspace secret to store, or whose value to replace.
  - `name` string, required: A workspace secret's name, which is also the environment variable each instance receives it as: uppercase letters, digits and underscores, not starting with a digit, at most 63 characters, and never starting `SANDBOX_`, which the sandbox reserves.
  - `value` string, password, required: The secret's value: 1 byte to 16 KiB of UTF-8. It is never returned.

## Response `200`

The workspace held the name; its value was replaced.

- SandboxSecret: A workspace secret: its name only, since the value never comes back.
  - `name` string, required: The secret's name.
  - `created_at` string, date-time, required

## Other responses

- `201`: Successful Response
- `400`: Invalid or failed-validation request.
- `401`: Authentication failed: missing, malformed, or invalid credentials.
- `403`: Insufficient scope or plan. `PERMISSION_DENIED`: you are not an owner or admin of the workspace. A workspace service key never is.
- `404`: Your workspace has no sandbox account.
- `429`: Rate limit exceeded.
- `500`: Internal error.
- `503`: Sandboxes are temporarily unavailable, or are still being set up for your workspace; retry shortly.

## Changes

- **2026-10-23** `e733493214f4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hedra-labs/apis/hedra-api/changes/sandboxes/secrets/post.md)

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)