Device provisioning MQTT API - AWS IoT Core

Device provisioning MQTT API

The Fleet Provisioning service supports these MQTT APIs:

This API supports response buffers in Concise Binary Object Representation (CBOR) format and JavaScript Object Notation (JSON), depending on the payload-format of the topic. For the sake of clarity, however, the response and request examples in this section are shown in JSON format.

payload-format Response format data type
cbor Concise Binary Object Representation (CBOR)
json JavaScript Object Notation (JSON)
Important

Before publishing a request message topic, subscribe to the response topics to receive the response. The messages used by this API use MQTT's publish/subscribe protocol to provide a request and response interaction.

If you do not subscribe to the response topics before you publish a request, you might not receive the results of that request.

CreateCertificateFromCsr

Creates a certificate from a certificate signing request (CSR). The new certificate has a PENDING_ACTIVATION status. When you call RegisterThing to provision a thing with this certificate, the certificate status changes to ACTIVE or INACTIVE as described in the template.

CreateCertificateFromCsr request

Publish a message with the $aws/certificates/create-from-csr/payload-format topic.

payload-format

The message payload format as cbor or json.

CreateCertificateFromCsr request payload

{ "certificateSigningRequest": "string" }
certificateSigningRequest

The CSR, in PEM format.

CreateCertificateFromCsr response

Subscribe to $aws/certificates/create-from-csr/payload-format/accepted.

payload-format

The message payload format as cbor or json.

CreateCertificateFromCsr response payload

{ "certificateOwnershipToken": "string", "certificateId": "string", "certificatePem": "string" }
certificateOwnershipToken

The token to prove ownership of the certificate during provisioning.

certificateId

The ID of the certificate. Certificate management operations only take a certificateId.

certificatePem

The certificate data, in PEM format.

CreateCertificateFromCsr error

To receive error responses, subscribe to $aws/certificates/create-from-csr/payload-format/rejected.

payload-format

The message payload format as cbor or json.

CreateCertificateFromCsr error payload

{ "statusCode": int, "errorCode": "string", "errorMessage": "string" }
statusCode

The status code.

errorCode

The error code.

errorMessage

The error message.

CreateKeysAndCertificate

Creates new keys and a certificate. The new certificate has a PENDING_ACTIVATION status. When you call RegisterThing to provision a thing with this certificate, the certificate status changes to ACTIVE or INACTIVE as described in the template.

CreateKeysAndCertificate request

Publish a message on $aws/certificates/create/payload-format with an empty message payload.

payload-format

The message payload format as cbor or json.

CreateKeysAndCertificate response

Subscribe to $aws/certificates/create/payload-format/accepted.

payload-format

The message payload format as cbor or json.

CreateKeysAndCertificate response

{ "certificateId": "string", "certificatePem": "string", "privateKey": "string", "certificateOwnershipToken": "string" }
certificateId

The certificate ID.

certificatePem

The certificate data, in PEM format.

privateKey

The private key.

certificateOwnershipToken

The token to prove ownership of the certificate during provisioning.

CreateKeysAndCertificate error

To receive error responses, subscribe to $aws/certificates/create/payload-format/rejected.

payload-format

The message payload format as cbor or json.

CreateKeysAndCertificate error payload

{ "statusCode": int, "errorCode": "string", "errorMessage": "string" }
statusCode

The status code.

errorCode

The error code.

errorMessage

The error message.

RegisterThing

Provisions a thing using a pre-defined template.

RegisterThing request

Publish a message on $aws/provisioning-templates/templateName/provision/payload-format.

payload-format

The message payload format as cbor or json.

templateName

The provisioning template name.

RegisterThing request payload

{ "certificateOwnershipToken": "string", "parameters": { "string": "string", ... } }
certificateOwnershipToken

The token to prove ownership of the certificate. The token is generated by AWS IoT when you create a certificate over MQTT.

parameters

Optional. Key-value pairs from the device that are used by the pre-provisioning hooks to evaluate the registration request.

RegisterThing response

Subscribe to $aws/provisioning-templates/templateName/provision/payload-format/accepted.

payload-format

The message payload format as cbor or json.

templateName

The provisioning template name.

RegisterThing response payload

{ "deviceConfiguration": { "string": "string", ... }, "thingName": "string" }
deviceConfiguration

The device configuration defined in the template.

thingName

The name of the IoT thing created during provisioning.

RegisterThing error response

To receive error responses, subscribe to $aws/provisioning-templates/templateName/provision/payload-format/rejected.

payload-format

The message payload format as cbor or json.

templateName

The provisioning template name.

RegisterThing error response payload

{ "statusCode": int, "errorCode": "string", "errorMessage": "string" }
statusCode

The status code.

errorCode

The error code.

errorMessage

The error message.