---
title: "Create a secret"
method: POST
path: "/secret"
tags: ["Secrets"]
---

# Create a secret

`POST /secret`

Create a secret. The value is encrypted at rest and never returned — the
response contains only the name. Reference it by name from a tool's `auth`.

## Request body

- CreateSecretRequest
  - `name` string, required — Secret name (letters, numbers, and underscores). Referenced from a tool's `auth`.
  - `value` string, required — The secret value. Write-only — encrypted at rest and never returned.

## Response `201`

Secret created (name only).

- object
  - `status` boolean
  - `data` Secret — A secret in the org Secrets vault. **Write-only**: the plaintext value is never returned by the API. Referenced by `name` from a tool's `auth` block; decrypted and injected into the outbound request server-side at call time.
    - `_id` string
    - `name` string
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `400` — Invalid input
- `401` — Unauthorized access
- `403` — Forbidden access
- `500` — Internal server error

## Changes

- **2026-09-02** `8546eaa96566` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/smallest-inc/apis/agent-management-api/changes/secret/post.md)

---

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