---
title: "Create or replace a secret value"
method: PUT
path: "/app/{id}/secrets"
---

# Create or replace a secret value

`PUT /app/{id}/secrets`

## Request

- Base URL: `https://charm.ing`
- URL: `https://charm.ing/app/{id}/secrets`
- Auth: HTTP bearer

Owner-only, write-only. Stores an encrypted secret value under a name, replacing any existing secret with the same name. The name must match `^[A-Z][A-Z0-9_]*$` (the same charset a `{{secret:NAME}}` reference uses, so a settable name is always referenceable); values are capped at 8 KiB. The value is never echoed back. Requires the owner's user token; app/render tokens are rejected.

## Request body

- object
  - `name` string, required: Env-var-shaped secret name (referenceable via `{{secret:NAME}}`).
  - `value` string, required: Plaintext secret value (max 8 KiB). Stored encrypted; never returned.

## Response `200`

Secret stored.

- OkResponse: Minimal success acknowledgement. `ok: true` confirms the mutation landed.
  - `ok` true, required

## Other responses

- `400`: Body is not JSON, name/value missing, name invalid, or value too large.
- `401`: User-scoped auth required.
- `403`: Caller does not own this app, or the app is anon-owned.
- `404`: App not found.

---

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