---
title: "Replace Secret"
method: PUT
path: "/api/v1/vault/secrets/by-alias/{alias}"
tags: ["vault"]
---

# Replace Secret

`PUT /api/v1/vault/secrets/by-alias/{alias}`

## Request

- Base URL: `https://core.mnemoverse.com`
- URL: `https://core.mnemoverse.com/api/v1/vault/secrets/by-alias/{alias}`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Replace the caller's ACTIVE secret with this alias by a new sealed value and context
(step 5): retire the old one (its stored value overwritten, its row kept as history), then store
the new one under the SAME alias. 404 when there is nothing to replace — a new name is
created with POST /vault/secrets, never by PUT. The body is validated BEFORE anything is
retired. The two steps are not one transaction (simplest first, 2026-10-10): if the
store fails after the retire, the error says so, the alias is free, and the caller
stores again with POST; the agent sees "no such alias" in between, never a stale value.
The quota count leaves retired secrets out, so a replace never needs headroom.

## Path parameters

- `alias` string, required

## Request body

- ReplaceSecretRequest: PUT /vault/secrets/by-alias/{alias}: the new value and context for an alias that already holds an active secret. The alias is the path parameter.
  - `context` string, required: In-clear routing/usage context. Listed by GET /vault/secrets and kept in GET /memory/export as a row with atom_type 'secret'. Not returned by memory search (POST /memory/read, /memory/read-batch, /memory/query, /memory/recent), nor by the point reads by atom id or external_ref or the atom chain, which answer 404 as for an atom that does not exist. The single-tenant WS /memory/stream (off in multi-tenant deployments) still carries it.
  - `sealed_secret_b64` string, required: Base64 of the envelope-encrypted value bytes.
  - `concepts` string[]
  - `domain` string
  - `metadata` object

## Response `200`

Successful Response

- ReplaceSecretResponse
  - `atom_id` string, required
  - `alias` string, required
  - `replaced_atom_id` string, required
  - `retired_at` string, date-time, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Validation Error
- `429`: Rate limited
- `500`: Internal server error
- `503`: Service unavailable

---

[API](https://skmtc.dev/mnemoverse/apis/mnemoverse-core.md) · [All operations](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/revisions/1f5e0048f017?raw)