get_installed_certificates

Reference·Audience: API consumer·Use: list the certificates installed in the reader's trust store

Overview

get_installed_certificates lists the certificates in the reader's trust store, returning per-certificate metadata — name, type, issuer/subject, serial, public-key algorithm, and validity dates — under installedCerts.certInfo[]. It is read-only and returns no private-key material. Use it to audit the certificate inventory and to confirm a certificate exists (and is valid) before referencing it from config_endpoint or set_wifi.

Details

Property	Value
Interaction Pattern	Request / Response (app publishes a command; device publishes the correlated reply)
State Change	READ-ONLY
Required Request Fields	command, requestId
Applies To	Endpoint: Management (MGMT). Reader: RFD40 series, RFD90 series
API Version	V1.1 (API Version Reporting)
Related	install_certificate, delete_certificate, config_endpoint

When to Use

Use get_installed_certificates to audit or verify the reader's certificate inventory:

• Before configuring TLS — confirm the ca_cert / client_cert referenced by config_endpoint (MQTT_TLS) or set_wifi (Enterprise) is installed and of the right type.
• Rotation planning — check validTill (expiry) and validFrom (not-yet-valid) to schedule renewals before TLS handshakes start failing.
• Trust audit — review issuerName / subjectName / serial to confirm the expected CA chain.

Topic Mapping

Message	Direction	Topic	Note
Request	App → Reader	<tenantId>/MGMT/clients/cmnd/<serial>	On the management endpoint.
Response	Reader → 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.

Credentials are presented once at CONNECT. The requestId you send is echoed in the response so you can pair reply to request.

See Topics and Channels.

Key Fields

• certInfo[].type (response) — the certificate's scope (mqtt, wifi, filestore, client, server); a certificate installed for one type is not usable by another.
• certInfo[].name (response) — the certificate's name. Published examples show component identifiers (ca_cert, client_cert), not the logical name given to install_certificate; which the reader reports is unresolved.
• certInfo[].validTill / validFrom (response) — the validity window; an expired or not-yet-valid certificate causes TLS handshake failures.
• certInfo[].issuerName / subjectName / serial (response) — identify the certificate and its CA chain (note serial is truncated — see Response Semantics).
• response.code (response) — read this to determine success vs failure (see Response Codes).

Request Payload

The request is a minimal envelope — just command (the plural literal) and requestId. The command returns the full inventory; there are no filter parameters.

Example

Request payload

{

"command": "get_installed_certificates",

"requestId": "abc123"

}

Schema

Request payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	string	—	get_installed_certificates	Fixed command name — the plural get_installed_certificates (see the command-name note below).
2	requestId*	string	—	abc123	A unique identifier for the request; echoed back in the response.

Request Semantics

• Command literal. Send command: "get_installed_certificates". An unknown or bogus command value is silently dropped (no error, no reply), so a missing reply usually means a wrong command string.

Response Payload

On success the device returns the envelope (command, requestId, apiVersion, response) with the inventory under installedCerts.certInfo[]. The Example tab shows a five-certificate trust store: CA certificates for filestore, wifi and mqtt, and client certificates for mqtt and wifi.

Example

Response payload

{

"command": "get_installed_certificates",

"requestId": "abc123",

"apiVersion": "V1.21",

"installedCerts": {

"certInfo": [

{

"name": "ca_cert",

"type": "filestore",

"issuerName": "ExampleRoot",

"publicKeyAlg": "RSA",

"publicKey": "RSA",

"serial": "ed:83:dd:4a:47:dd:07:98",

"subjectName": "ExampleRoot",

"validFrom": "2024-07-01T07:00:00Z",

"validTill": "2034-02-28T15:18:47Z"

},

{

"name": "ca_cert",

"type": "wifi",

"issuerName": "CA",

"publicKeyAlg": "RSA",

"publicKey": "RSA",

"serial": "1e:e0:12:f6:75:68:39:f1",

"subjectName": "CA",

"validFrom": "2024-07-01T07:00:00Z",

"validTill": "2025-04-16T07:26:35Z"

},

{

"name": "ca_cert",

"type": "mqtt",

"issuerName": "Example-mqtt-ca",

"publicKeyAlg": "RSA",

"publicKey": "RSA",

"serial": "7d:1b:c5:9f:ea:ff:0f:56",

"subjectName": "Example-mqtt-ca",

"validFrom": "2024-07-01T07:00:00Z",

"validTill": "2038-01-19T03:14:07Z"

},

{

"name": "client_cert",

"type": "mqtt",

"issuerName": "RootCA",

"publicKeyAlg": "RSA",

"publicKey": "RSA",

"serial": "1",

"subjectName": "Client",

"validFrom": "2024-07-01T07:00:00Z",

"validTill": "2030-05-06T08:06:57Z"

},

{

"name": "client_cert",

"type": "wifi",

"issuerName": "CA",

"publicKeyAlg": "RSA",

"publicKey": "RSA",

"serial": "26:00:16:e0:c4:a1:b5:00",

"subjectName": "CLIENT",

"validFrom": "2024-07-01T07:00:00Z",

"validTill": "2025-04-16T07:27:52Z"

}

]

},

"response": {

"code": 0,

"description": "Success"

}

}

Schema

Response payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	string	—	get_installed_certificates	Echoes the executed command (plural).
2	requestId*	string	—	abc123	Echoes the request's requestId — pairs reply to request.
3	apiVersion*	enum	V1.0V1.1V1.2V1.21V1.22	V1.21	API version reported by this command. Emitted per-handler, not device-wide.
4	installedCerts	object	—	—	The certificate inventory. Present on success. (Not in the envelope required set.)
5	certInfo, nesting level 2	array	—	—	One entry per installed certificate. Each item requires type, issuerName, subjectName, validFrom, validTill.
6	name, nesting level 3	string	—	Reader Main Certificate	The name of the certificate. Every published example carries a certificate component identifier here (ca_cert, client_cert) rather than the logical name install_certificate accepts; which one the reader reports is unresolved.
7	type*, nesting level 3	enum	clientservermqttwififilestore	server	Certificate scope/type. Certificates are scoped by type — one installed for mqtt is not usable for wifi.
8	installTime, nesting level 3	string	date-time	2022-07-01T03:01:31.464Z	Install timestamp. Optional — the device often omits it.
9	issuerName*, nesting level 3	string	—	FX9600EE5729	Issuer common name.
10	publicKeyAlg, nesting level 3	enum	RSARSAMD5RSA_SHA_1RSA_SHA_256RSA_SHA_384RSA_SHA_512	RSA	Public-key algorithm reported by the device (e.g. RSA).
11	publicKey, nesting level 3	string	—	091234acgbe12	Public-key field. The device currently populates this with the algorithm name rather than key bytes (see Response Semantics).
12	serial, nesting level 3	string	—	ed:83:dd:4a:47:dd:07:98	Certificate serial as colon-hex — the first 8 bytes of the full serial (the device truncates; see Response Semantics).
13	subjectName*, nesting level 3	string	—	FX9600EE572	Subject common name.
14	validFrom*, nesting level 3	string	date-time	2024-07-01T07:00:00Z	Start of the validity window.
15	validTill*, nesting level 3	string	date-time	2034-02-28T15:18:47Z	End of the validity window.
16	response*	object	—	—	Status envelope for the read.
17	code*, nesting level 2	integer	0–101	0	0 = Success; non-zero = error. Required by the contract. See Response Codes below.
18	description*, nesting level 2	string	—	Success	Human-readable status.

Response Semantics

• serial is truncated to 8 bytes. The device returns the certificate serial as colon-delimited hex, but only the first 8 bytes of the (typically 20-byte) real serial — e.g. 7d:ef:d4:c3:2d:39:4a:0b. Combine serial with name + type + issuerName to identify a certificate uniquely; serial alone is not a globally unique identifier.
• Private keys are never listed. The inventory returns public certificate metadata only. A client_key installed via install_certificate does not appear in certInfo[] — only its paired ca_cert / client_cert do. There is no way (by design) to read back private-key material.
• publicKey and publicKeyAlg quirks. The device currently populates publicKey with the algorithm name (e.g. RSA) rather than actual key bytes — treat publicKey as informational, not as usable key material. publicKeyAlg reports the certificate's public-key algorithm — an RSA variant (see the allowed values under Response Payload).

Response Codes

get_installed_certificates 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.

Code	Description
0	Success — the inventory was retrieved (an empty trust store still returns 0 with an empty/absent certInfo).
3	Not able to retrieve information (IOT_ERROR_INFO_NOT_AVAILABLE) — the device could not gather the certificate list at this time. Retry after a short delay; if persistent, reboot.
9	File not found (IOT_STATUS_FILE_NOT_FOUND) — a backing certificate file could not be found.
21	Certificate not found (IOT_ERROR_CERT_NOT_FOUND) — the requested certificate is not installed.
101	Default error — generic catch-all.

Codes 3 / 9 / 21 are this command's mapped failure codes. The request takes no parameters; send exactly command + requestId.

Examples

Publish the plural get_installed_certificates with a requestId; the device replies with the inventory shown under Response Payload. The command always returns the full list and takes no parameters (there are no request variants).

Notes and Caveats

Read-only, but still sensitive. The inventory exposes no secrets (no private keys), but a certificate list reveals the device's PKI/trust topology — redact it in shared logs, tickets, and screenshots. For the concept-level view, see TLS and Authentication and Certificate Management.

Related: 📕 TLS and Authentication · 📕 install_certificate · 📕 delete_certificate · 📕 config_endpoint · 📕 set_wifi · 📕 Response Codes