---
title: "Create a new secret value"
method: POST
path: "/app/{id}/secrets"
---

# Create a new secret value

`POST /app/{id}/secrets`

## Request

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

Owner-only, write-only. Creates a new encrypted secret value under a 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. Returns 409 `secret_already_exists` if a secret with the same name already exists for this scope; use PUT to replace it. 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.
- `409`: A secret with this name already exists; use PUT to replace, or DELETE it first.

---

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