# DeleteSecret deletes a secret; deleting an already absent secret succeeds. [API catalog](/reference/api/) · [Docker Sandboxes overview](/reference/api/sandboxes/latest/) · [Product manual](https://docs.docker.com/ai/sandboxes-api/) · [OpenAPI specification](/reference/api/sandboxes/api.yaml) API version: v1 > This API is experimental. Features, interfaces, > and behavior may change. `DELETE /v1/secrets/{secret}` DeleteSecret deletes a secret; deleting an already absent secret succeeds. Its response carries the credential fence receipt, so it answers 200 with a body rather than the 204 an empty-response delete declares. Returns unimplemented when this operation is unavailable. Support does not grant permission. ## Connection and access [API connection and authentication guidance](/reference/api/sandboxes/latest/#authentication) Server: `https://connect.docker.com/sandboxes` Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement. ```json [ { "bearer": [] } ] ``` ## Example request Replace placeholders and provide the required credentials or request body. ```console curl \ --request DELETE \ --header 'If-Match: ' \ --header "Authorization: Bearer ${TOKEN}" \ --header 'Accept: application/json' \ 'https://connect.docker.com/sandboxes/v1/secrets/' ``` ## Parameters ### secret Location: path. Required: yes. The secret id. ```json { "description": "The secret id.", "in": "path", "name": "secret", "pointer": "/paths/~1v1~1secrets~1{secret}/delete/parameters/0", "required": true, "schema": { "type": "string" } } ``` ### If-Match Location: header. Required: yes. The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body. ```json { "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", "in": "header", "name": "If-Match", "pointer": "/paths/~1v1~1secrets~1{secret}/delete/parameters/1", "required": true, "schema": { "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", "title": "If-Match", "type": "string" } } ``` ## Request and responses ### Response 200 application/json Success Schema: ```json { "$ref": "#/components/schemas/DeleteSecretResponse" } ``` ### Response 412 application/json The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` etag_mismatch: ```json { "code": "failedPrecondition", "details": [ { "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", "currentEtag": "v2" } ], "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." } ``` ### Response 428 application/json No precondition was sent. The body carries failedPrecondition naming etag_required. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` etag_required: ```json { "code": "failedPrecondition", "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." } ``` ### Response 501 application/json This operation is not available on this service. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` unimplemented: ```json { "code": "unimplemented", "message": "This operation is not available on this service." } ``` ### Response default application/json The structured Error body identifies the failure with a stable code and optional typed details. Schema: ```json { "$ref": "#/components/schemas/Error" } ``` Schema example: ```json { "code": "notFound", "details": [], "message": "sandbox not found" } ``` ## Complete operation contract ```json { "description": "DeleteSecret deletes a secret; deleting an already absent secret succeeds.\nIts response carries the credential fence receipt, so it answers 200 with a\nbody rather than the 204 an empty-response delete declares.\n\nReturns unimplemented when this operation is unavailable. Support does not grant permission.", "operationId": "deleteSecret", "parameters": [ { "description": "The secret id.", "in": "path", "name": "secret", "required": true, "schema": { "type": "string" } }, { "description": "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body.", "in": "header", "name": "If-Match", "required": true, "schema": { "description": "etag is the required precondition, the value the target's last read returned.\nAn absent one refuses etag_required and a stale one etag_mismatch.", "title": "If-Match", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSecretResponse" } } }, "description": "Success" }, "412": { "content": { "application/json": { "examples": { "etag_mismatch": { "summary": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value.", "value": { "code": "failedPrecondition", "details": [ { "@type": "type.googleapis.com/docker.sandboxes.v1.EtagMismatch", "currentEtag": "v2" } ], "message": "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." }, "428": { "content": { "application/json": { "examples": { "etag_required": { "summary": "No precondition was sent. The body carries failedPrecondition naming etag_required.", "value": { "code": "failedPrecondition", "message": "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No precondition was sent. The body carries failedPrecondition naming etag_required." }, "501": { "content": { "application/json": { "examples": { "unimplemented": { "summary": "This operation is not available on this service.", "value": { "code": "unimplemented", "message": "This operation is not available on this service." } } }, "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "This operation is not available on this service." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "The structured Error body identifies the failure with a stable code and optional typed details." } }, "security": [ { "bearer": [] } ], "summary": "DeleteSecret deletes a secret; deleting an already absent secret succeeds.", "tags": [ "Secrets" ], "x-sbx-authenticated-only": false, "x-sbx-conditional-permissions": [], "x-sbx-error-responses": [ { "code": "UNIMPLEMENTED", "description": "This operation is not available on this service." } ], "x-sbx-plane": "control", "x-sbx-required-permissions": [ "secretsWrite" ], "x-sbx-serving-surface": "management" } ``` ## Referenced schemas - [#/components/schemas/DeleteSecretResponse](/reference/api/sandboxes/latest/schemas/DeleteSecretResponse/) - [#/components/schemas/Error](/reference/api/sandboxes/latest/schemas/Error/)