delete_secret

{
  "name": "delete_secret",
  "resource": "secret",
  "tier": "destructive",
  "summary": "End one stored value through the pending action, its description rendered from the custody index: the entry leaves the index and no caller reads the value again, the vault holding it in its soft delete for its retention window. A platform-minted name, and a name a binding, an upstream, a realm route, or a push provider uses, is refused.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": false
  }
}

{
  "name": "delete_secret",
  "tier": "destructive",
  "scenario": "CHI-L0-08",
  "summary": "Delete one stored secret by its name and scope: a value stored under the wrong name or at the wrong scope, or one no longer needed. The `application` and `environment` arguments name the scope as for `store_secret`. Destructive: needs a credential holding the destructive class (a signed-in session, or an account-wide token minted with `destructive`); the call creates a pending action, and the deletion runs only after a person approves it in the browser.\n\nOnce it runs, the name leaves custody and no caller reads the value again. The vault holds the deleted value in its soft delete for its retention window, and no action reads or restores it. A store under the same name afterwards is a new value.\n\nA platform-minted name is refused `platform_minted_name`. A name still in use is refused `secret_in_use`: one a binding feeds, where the recorded manifest, a running copy, or an act in flight holds it, an upstream's key, or a realm route's or a push provider's credential. A use begun before the approval ends the pending action declined, and one begun after it ends the action failed with `secret_in_use`. A value already gone, or re-supplied, rotated, or stored again since the approval, completes with `deleted` false, and nothing is deleted.",
  "owners": [
    "SCRT-L0-07",
    "SCRT-L0-08",
    "SEC-L0-07",
    "MAN-14",
    "API-L0-07",
    "MAPI-05"
  ]
}

{
  "request": {
    "type": "object",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
        "description": "The stored name to delete, as `list_secrets` lists it."
      },
      "application": {
        "type": "string",
        "description": "The application id whose scope holds the secret; omitted, the account scope."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional, and it rides `application`: the environment whose scope of that application holds the secret, `development` or `production`; absent, `production`. Each environment's value is deleted on its own call."
      },
      "request_id": {
        "type": "string",
        "description": "Your request identity for this pending action: any string you choose. Repeating the call with the same request_id, from the same account, while the earlier pending action is still live — requested, approved, or executing — answers that pending action again and creates no second one. Once it has completed, failed, been declined, or expired, the same request_id starts a new one. Omitted, every call creates a new pending action."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "description": "The 202 creation envelope: the pending action and its approval link (API-L0-07); the terminal outcome rides the pending record via read_pending_action. A completed outcome carries `deleted`, the `secret` with its `name`, `scope`, `application`, and `environment`, and a `detail`. Where `deleted` is true the detail discloses the vault's retention window (SCRT-L0-07); where it is false the value was already gone, or was re-supplied, rotated, or stored again since the approval. A use made after the approval ends the record `failed` with `secret_in_use`.",
    "required": [
      "contract_version",
      "pending_action",
      "approval_url"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
      },
      "pending_action": {
        "$ref": "#/shapes/pending_action"
      },
      "approval_url": {
        "type": "string"
      },
      "detail": {
        "type": "string"
      }
    }
  }
}