---
title: "Management secret deletion"
description: "Delete a stored environment secret by path, query, or JSON body."
type: reference
product: platform
summary: "Bodyless DELETE forms for the management secret store."
updated: 2026-10-08
---

# Delete a management secret

The management secret store accepts all three forms below. Each uses the same
Authorization bearer credential, organization/project/environment authorization,
soft deletion, version retention, dependency checks and audit writer. This is the
management API, not the Resource API's named secret deletion.

| Form | Request |
| --- | --- |
| Path (preferred) | `DELETE /v1/secrets/{sec_id}` |
| Query | `DELETE /v1/secrets?id=sec_xxx` |
| JSON body (compatible) | `DELETE /v1/secrets` with `{"id":"sec_xxx"}` |

The `/api/v1` prefix also accepts these forms. A secret id is a `sec_` TypeID
or UUID. Different ids supplied through the path, query or body are rejected
with `400 conflicting_secret_id`; equivalent UUID and TypeID representations
are accepted. Invalid ids return `400 invalid_secret_id`.

Use `reason` in the query for a bodyless request, or in the JSON body. The audit
entry records it as `metadata.reason`. If both supply a reason, they must match.
No secret value is needed or returned.

```bash
curl -X DELETE "https://api.sylphx.com/v1/secrets/$SECRET_ID?reason=retire%20unused%20secret" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"

curl -X DELETE "https://api.sylphx.com/v1/secrets?id=$SECRET_ID&reason=retire%20unused%20secret" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"
```

Success returns `200` and the existing management response (`ok: true`). The
stored row and versions are retained, but subsequent
`GET /v1/secrets/detail?id=sec_xxx` returns `404 secret_not_found`, and the
ordinary list excludes the deleted row. A repeated deletion returns `404`.

A service credential requires `project:secrets:manage` (or an existing scope
that grants that capability) and must be bound to the secret's owning project
and environment. Human credentials use the existing secret-management role
checks. Supplying an id in the URL does not grant access to it.

A secret still in use returns `409 secret_in_use`. The existing `?force=true`
(or JSON `"force": true`) semantics are unchanged: an override is audited in
the mutation transaction, and failure to write that audit rolls it back with
`503 secret_audit_unavailable`. A reason does not override dependency checks.