Skip to main content

delete_certificate

ReferenceAudience: API consumerUse: remove a certificate (or all of a type) from the reader's trust store

Overview​

delete_certificate removes a certificate from the reader's trust store, identified by certificateInfo.{name, type}. It is synchronous — a successful delete returns response.code 0 and the certificate is gone immediately (confirm with get_installed_certificates). It is a state-changing command on the device-management (MGMT) endpoint.

delete_certificate is destructive and irreversible — and omitting certificateInfo.name deletes every certificate of the given type. See the danger callout in Notes and Caveats before sending.

Details​

PropertyValue
Interaction PatternRequest / Response (app publishes a command; device publishes the correlated reply)
State ChangeSTATE-CHANGING (removes a certificate, or all certificates of a type)
ReversibilityIRREVERSIBLE (no undo; re-install with install_certificate to restore)
Required Request Fieldscommand, requestId, certificateInfo (with type; name optional)
Applies ToEndpoint: Management (MGMT). Reader: RFD40 series, RFD90 series
API VersionV1.1 (API Version Reporting)
Relatedget_installed_certificates, install_certificate, config_endpoint, set_wifi

When to Use​

Use delete_certificate to clean up the reader's trust store:

  • Remove an obsolete or expired certificate — e.g. before rotating in a replacement.
  • Clear a slot before re-installing — delete then install_certificate with the same name.
  • Wipe a whole type — omit name to remove every certificate of a type (e.g. all wifi certificates) in one call. Use deliberately.

Delete only certificates that are not in active use. On a TLS endpoint, deleting the broker/client certificate the reader is currently connected with will break that connection.

Topic Mapping​

MessageDirectionTopicNote
RequestApp → Reader<tenantId>/MGMT/clients/cmnd/<serial>On the management endpoint.
ResponseReader → App<tenantId>/MGMT/clients/resp/<serial>Correlated reply to the request above; the in-payload requestId links the twin topics.

Topics follow the pattern <tenantId>/<topic>/<serial> — the tenant id assigned to you at provisioning (a slot you fill in, never a literal), the base topic you configure on the endpoint, and the reader's serial number, which the reader appends itself in its model-prefixed form (for example RFD40-212735201D0053). App → Reader means your app publishes and the reader subscribes; Reader → App means the reader publishes and your app subscribes.

delete_certificate identifies certificates by name/type only, so it carries no credential field — there is nothing to mask. The requestId you send is echoed in the response so you can pair reply to request.

See Topics and Channels.

Key Fields​

  • certificateInfo.type (request) — the certificate category (mqtt, wifi, filestore, client, server); required. Confirm exact names/types with get_installed_certificates first.
  • certificateInfo.name (request) — the certificate to delete. ⚠️ Omitting it deletes every certificate of type (bulk). Verify the exact name with get_installed_certificates (installed entries are named {name}_{component}).
  • response.code (response) — read this to determine success vs failure: 0 (deleted), 21 (no such certificate). See Response Codes.

Request Payload​

The envelope is command, requestId, and the certificateInfo object naming the certificate to delete. Pick a certificate type below; the Example and Schema update together. Use the Schema tab for the full field reference and the Example tab for a single-certificate delete.

Request payload
Example: wifi / ca_cert
{
"command": "delete_certificate",
"requestId": "abc123",
"certificateInfo": {
"name": "ca_cert",
"type": "wifi"
}
}

To delete every certificate of a type, omit name and send only type — a destructive bulk operation:

Request — bulk delete (all wifi certificates)
{
"command": "delete_certificate",
"requestId": "abc123",
"certificateInfo": {
"type": "wifi"
}
}

Request Semantics​

  • certificateInfo is required, and so is the type inside it. The contract requires the payload outright, and the device agrees — a request without it is rejected with code 101. Always send certificateInfo with at least a valid type.
  • Type-null certificates cannot be deleted. delete_certificate matches on type, so a certificate that install_certificate created without a type (type: null, which the installer accepts) matches no type value and returns code 21 for every attempt — it becomes un-deletable through this command. Avoid the situation by always sending type to install_certificate; to clear an existing orphan, re-install the same name with an explicit type.

Response Payload​

delete_certificate returns a status-only envelope — command, requestId, apiVersion, and response. There is no certificate echo; confirm the removal with get_installed_certificates.

Response payload
{
"command": "delete_certificate",
"requestId": "abc123",
"apiVersion": "V1.1",
"response": {
"code": 0,
"description": "Success"
}
}

Response Codes​

delete_certificate returns response.code. The codes applicable to this command are below; for the full table see the Response Codes and Correlation and Request/Response Pairing.

CodeDescription
0Success — the matching certificate (or all of the type) was removed.
9File not found (IOT_STATUS_FILE_NOT_FOUND) — a backing certificate file could not be found.
21Certificate not found (IOT_ERROR_CERT_NOT_FOUND) — the name/type is not a saved certificate. See the not-found note below.
101Default error — generic catch-all (e.g. a malformed payload; see the note below).

Two live-observed behaviors to code against: (1) A not-found delete returns code 21 but with the description text "File not found" (the wording of code 9) — key on the numeric 21, not the string. (2) A malformed payload — a missing required type, or a missing certificateInfo — returns the generic 101 ("Default error"), while an invalid type value returns 23 ("Invalid enum value"). Gate success strictly on code == 0.

Examples​

Publish delete_certificate naming the certificate to remove; the device replies with the status-only envelope under Response Payload. The bulk-delete request (omit name) is shown under Request Payload.

Targeting a name/type that is not installed returns code 21 (note the "File not found" description):

Response — certificate not found (code 21)
{
"command": "delete_certificate",
"requestId": "abc123",
"apiVersion": "V1.1",
"response": {
"code": 21,
"description": "File not found"
}
}

Notes and Caveats​

Irreversible — and omitting name wipes every certificate of the type

There is no undo and no confirmation prompt. A delete_certificate with certificateInfo.type but no name deletes every certificate of that type. Always include an explicit name unless a full type-wipe is intended, and verify the exact name first with get_installed_certificates. Never delete a certificate an active TLS connection relies on — doing so breaks that connection. Recovery in every case means re-installing with install_certificate.

Because the response is status-only, verify the result with get_installed_certificates — confirm the deleted name/type no longer appears. For the concept-level view, see TLS and Authentication and Certificate Management.

Related: 📕 TLS and Authentication · 📕 get_installed_certificates · 📕 install_certificate · 📕 config_endpoint · 📕 Response Codes

Was this helpful?