Certificates

This page describes the Spoke Zone Certificates API, which is used to update the HTTPS and MQTT certificates used by devices in the field.

No authentication is required for these endpoints, but devices will be blocked if they make too many requests in a short period of time.

Fields

The following fields are valid across all the certificate endpoints.

• The server field specifies which server to get a certificate for
  • Valid options:
    • api - Refers to the server at https://api.spoke.zone.
    • mqtt-broker - Refers to the server at wss://io.spoke.zone.
• The certificateName field specifies which certificate to get for the server
  • Valid options:
    • primary - Use this for secure communication for the server.
    • secondary - Use this as a fallback for when the primary certificate becomes expired. Use only when communication using the primary certificate fails.
• An optional encoding query parameter controls how certificates are represented or processed across certificate endpoints.
  • Valid options:
    • pem - Certificates are handled in their PEM format (default).
    • der - Certificates are converted to DER format (binary ASN.1, base64-decoded).
  • Behavior:
    • In the file API, encoding determines the returned file format (.pem or .der).
    • In the hash API, encoding determines whether the hash is computed on the PEM bytes or the DER bytes.

Download Certificate Endpoint

GET /api/v2/certificates/:server/:certificateName/file to download the contents of a certificate.

• If a device tries to download a certificate too often, it will receive a 429 status

Example

Request:

GET /api/v2/certificates/api/primary/file

Response:

(the contents of the primary HTTPS certificate for the API server)

Certificate Hash Endpoint

GET /api/v2/certificates/:server/:certificateName/hash to get the hash of a certificate.

• The response will be a JSON object with a single key: hash.
• The hash will be returned as a hexadecimal string.
• If a device tries to request a certificate hash too often, it will receive a 429 status
• An optional algorithm query parameter can be included to specify the hash algorithm used.
  • Valid options:
    • sha256 - default
    • md5 - not recommended, included for devices that don’t support sha256
• An optional encoding query parameter can be provided to control how the certificate content is processed before computing the hash.
  • Valid options:
    • pem - Hash is computed directly on the raw PEM-encoded bytes (default)
    • der - PEM certificate is converted to DER (binary form via base64 decoding) and the hash is then computed on the DER bytes

Example

Request:

GET /api/v2/certificates/mqtt-broker/secondary/hash?algorithm=sha256&encoding=pem

Response:

{ hash: "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f" }