---
title: "Create or update a secret"
method: POST
path: "/functions/{id}/secrets"
tags: ["Functions"]
---

# Create or update a secret

`POST /functions/{id}/secrets`

Idempotent insert-or-update keyed on `(function_id, key)`.
Returns 201 the first time the key is set, 200 on subsequent
updates. Values are encrypted at rest and only become visible
to the running handler on the next deploy (`PUT /functions/{id}`
with the existing code is sufficient to refresh bindings).

Keys must match `^[A-Z_][A-Z0-9_]*$` (uppercase letters,
digits, underscores; first character is a letter or
underscore). Values are at most 4096 UTF-8 bytes. System-
managed keys are reserved and rejected.

## Headers

- `Idempotency-Key` string

## Request body

- object — Body for POST /functions/{id}/secrets.
  - `key` string, required — Uppercase letters, digits, and underscores. Must start with a letter or underscore. System-managed keys (e.g. PRIMITIVE_WEBHOOK_SECRET, PRIMITIVE_API_KEY, and PRIMITIVE_API_BASE_URL) are reserved.
  - `value` string, required — Secret value, up to 4096 UTF-8 bytes. Encrypted at rest. Never returned by any read endpoint.

## Response `200`

Secret updated

- object
  - `success` true, required
  - `data` object, required — Returned by POST and PUT secret routes.
    - `key` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `created` boolean, required — True if this call inserted a new row, false if it updated an existing one.

## Other responses

- `201` — Secret created
- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `404` — Resource not found

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) · [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primitive/primitive-api/revisions/c2299d28022c/schema)