Renew device certificate by device ID (client authentication)

Endpoint URL

generic
POST https://clientauth.one.digicert.com/iot/api/v2/device/{{device_id}}/renew

Use this endpoint to renew an existing certificate for a device.

This endpoint supports mutual TLS authentication. This means a client can access the endpoint by presenting a trusted certificate in the request instead of using an API key.

Use TLS authentication when:

  • You need to configure a device to read and update its own data.
  • You do not want to allow the device to read and write data for other devices or access endpoints that require an API key.

To access this endpoint with TLS authentication:

  • The certificate in the API request must be a certificate that is associated with the device.
  • The device_api_allow_renew property for the device must be set to true.
    To change the value of this property, use the Update device by ID endpoint. Alternatively, edit the settings for the device from the IoT Device Manager console.

Example requests and responses

To use this example, replace {{my_private_key.key}} and {{my_custom_certificate.pem}} with the filenames or path to the location for your private key and certificate.

cURL
curl --request POST 'https://clientauth.one.digicert.com/iot/api/v2/device/{{device_id}}/renew' \
--header 'Content-Type: application/json' \
--cert {{my_custom_certificate.pem}} \
--key {{my_private_key.key}} \
--data-raw '{
  "csr": "{{csr}}",
  "certificate_profile_attributes": [
    {
      "id": "subject.organization_name",
      "value": "custom org name"
    }
  ],
  "device_attributes": [
    {
      "id": "party-no",
      "value": "PN8363454893"
    },
    {
      "id": "comments",
      "value": "new custom comments"
    }
  ]
}'
200 OK
{
  "certificate_request_id": "208f6d2e-dda6-4f47-9db1-95375ab792d3",
  "status": "AUTO_APPROVED",
  "result": "SUCCESS",
  "certificate_id": "fa39ba51-b556-4a1a-bd78-75e46fa86be7",
  "pem": "-----BEGIN CERTIFICATE-----\nMIIC8TCCAdmgAwIBAgIUSyxE6XLp8Stcnh3APZv5peoD7u4wDQYJKoZIhvcNAQELBQAwgYQxEDAOBgNV\nBAYTB1VrcmFpbmUxCzAJBgNVBAgTAk5BMQ0wCwYDVQQHEwRLeWl2MQ0wCwYDVQQJEwRLeWl2MQ4wDAYD\nVQQREwUwMzEyNzEUMBIGA1UEChMLSW9UIENvbXBhbnkxHzAdBgNVBAMTFklvVCBDb21wYW55IElzc3Vp\nbmcgQ0EwHhcNMjAwNTE4MDgyODM2WhcNMjQwNTMwMjEwMDAwWjA0MRgwFgYDVQQKEw9jdXN0b20gb3Jn\nIG5hbWUxGDAWBgNVBAMTD05ldyBDb21tb24gTmFtZTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPJk\nO9S7qs9CJzecWtFY0eRpFzDJ2cpDn7x3y13/BEGoAqTRs/aiFuf8easLeaTt2Pl0oGnOVggGlcW8E+fb\n0EKjdTBzMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFJShbUKjZhHpaUHDIhsZdP5LcqASMB8GA1UdIwQY\nMBaAFLcZq70zfTTHOdJWR6093AwDvN9PMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcD\nAjANBgkqhkiG9w0BAQsFAAOCAQEAMDQhNZlF3sr+Qu5q7KhuMbUYpodBwZBoAeXBYbguBLueDwaPS74p\ncwXM5ipDQZfUF9NmNyEQ/6MOGQmczRD8h/QjVVvT5HTrEsSUNb8zjcLU+qh36G7A9WFqN9YT0+7vf2oq\n5GSYXyxWqhBWAhPsBVoCrSjtTEpAezNNLerI3ii7hzgw60/WIx7aQV+HJvpyVnswtFTovGBGNsYJnM8S\nOmpOgC8DfAyCTeF5qolwDmVPiJGJkzDKZYmlZ8ud/MtXzGGEzeBm8Yx4nYfR8TKFLQuY8JwAUkA50QjB\n4RvLF4EXuBPJTAgfTWSwvbCjguVude79SrwOtIYUpMH6HdgUpw==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIID1DCCArygAwIBAgIUKlINzekDRdxbQVRP5KaksaiqSXYwDQYJKoZIhvcNAQELBQAwgYExEDAOBgNV\nBAYTB1VrcmFpbmUxCzAJBgNVBAgTAk5BMQ0wCwYDVQQHEwRLeWl2MQ0wCwYDVQQJEwRLeWl2MQ4wDAYD\nVQQREwUwMzEyNzEUMBIGA1UEChMLSW9UIENvbXBhbnkxHDAaBgNVBAMTE0lvVCBDb21wYW55IFJvb3Qg\nQ0EwHhcNMjAwNTE0MDkyMDUyWhcNMjQwNTMwMjEwMDAwWjCBgTEQMA4GA1UEBhMHVWtyYWluZTELMAkG\nA1UECBMCTkExDTALBgNVBAcTBEt5aXYxDTALBgNVBAkTBEt5aXYxDjAMBgNVBBETBTAzMTI3MRQwEgYD\nVQQKEwtJb1QgQ29tcGFueTEcMBoGA1UEAxMTSW9UIENvbXBhbnkgUm9vdCBDQTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBALPy9NXQKucPXpJqRJbYwOP94jmDZcnJl8vn93ei8bnajGKny3Y0y1cE\nJm0YcVxgD2tOCcDlX4It7lY5gmw/WL5R7oW5vdiOCCcQYLqKvOFXL+p7kDD/7y3IfaFdwbvfgHyvtwX1\nSZUQvk61BFJ6kzvkLA27P1EjhAxeRX9ktB4896uTF7NIFE5HmajOU1p1EiQK9sBDoPMXTIfW+sS4BaBD\nxTc84R18OwC+LPxcIMSGwcWPvoRYGBkvD/XVu7IEe8pyV9+c1vt/4XD+VctqYA2bktOqXh9Xc6PlXfIA\nVhMJRdojDQG35YM5AUKbGFFXGsNt6Iko2Jzo3s5RWP+Vx0UCAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB\n/zAdBgNVHQ4EFgQUXgrl0LDaYAs/E/nzaYgZiy7tewYwDgYDVR0PAQH/BAQDAgGGMA0GCSqGSIb3DQEB\nCwUAA4IBAQBmV/Gq0G+gO4wKhVYfd6Kg+VhkEqi7GWQVVUfbrSNXtpyEP8SPxyjPHMBIDKwKodxHrE99\n4WN+yhQto01OKk0s3X4uMIVFcKsO3XtdZYyh1dWh+3cCtF5SaqIxbREBBjkE4ImDvTSJPwzQtfmHBWxA\nIZN4tyiBeKZIqqZJgvSMyBR8wMI4FaGYLch9tZmdAHSwYu7ITKR0nOpDxHT1zg/hT7q2judxTy/G7wLT\nm2FkEhikpM2CqEuH6EAp5McyVi/n1BPNU3Kt3ViRQ4tdoR7fcJAwklCdhIvsP4F/RyQE+X+2VU+KfZqc\nMUzHKvsbQig1L8yUXQevdUQWYJT2nlg/\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIID+DCCAuCgAwIBAgIUIJfeCwm5SEKRwB/2UqvwuVfVAlMwDQYJKoZIhvcNAQELBQAwgYExEDAOBgNV\nBAYTB1VrcmFpbmUxCzAJBgNVBAgTAk5BMQ0wCwYDVQQHEwRLeWl2MQ0wCwYDVQQJEwRLeWl2MQ4wDAYD\nVQQREwUwMzEyNzEUMBIGA1UEChMLSW9UIENvbXBhbnkxHDAaBgNVBAMTE0lvVCBDb21wYW55IFJvb3Qg\nQ0EwHhcNMjAwNTE0MDkyMTE3WhcNMjQwNTMwMjEwMDAwWjCBhDEQMA4GA1UEBhMHVWtyYWluZTELMAkG\nA1UECBMCTkExDTALBgNVBAcTBEt5aXYxDTALBgNVBAkTBEt5aXYxDjAMBgNVBBETBTAzMTI3MRQwEgYD\nVQQKEwtJb1QgQ29tcGFueTEfMB0GA1UEAxMWSW9UIENvbXBhbnkgSXNzdWluZyBDQTCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBAK2f0+1yTE/1X8L010GXlTah/j1lyypTzZ9YN72CohKhllFORTn7\nHhddEfxD2utUirtS2xKoxIP+EV6LmbJYJmp5xW/1tosrq3Js5MfWCuNd/5kSpVfDxvVw2sJldTQ0CIgc\nLwA7NQAH994TyUQVzkhmcVmkaVLylFutVyXybXI19drl53bv5kyAEX3Met5WObdcy6wVE5DFfnj/BDSl\nvYOMLjA8khAlUclTe96+0WojWxun8GY6SM6C1N+9T768orq7GHIt0Bi2kNA6P6LTT63qCTlPmkgEcUgk\ngoHBxIzGAedisJ7bbdcbLE1jq+AG+Uj9vXCL68aU3rfcO+csGsUCAwEAAaNjMGEwDwYDVR0TAQH/BAUw\nAwEB/zAdBgNVHQ4EFgQUtxmrvTN9NMc50lZHrT3cDAO8308wHwYDVR0jBBgwFoAUXgrl0LDaYAs/E/nz\naYgZiy7tewYwDgYDVR0PAQH/BAQDAgGGMA0GCSqGSIb3DQEBCwUAA4IBAQB0l/ASL+JNjb7QNALcY9GR\n9tQFUKSSTmVyyML0ajGS5/dEXcxWH/Wb+lmihxkXXd55bZfWBs+Te9ksVA7X284MZFffSYXwd+CTy4Qb\nOatMkFGHwYpt4nWbi5W5phtBS1AEesdMd0PSBDaRWkJttWJz6Tk6aiz6pAuDwAXyau/crdlwx29soOdg\nWwD95kkRrF9hYNATa3kPR+Zin31d9osRtc3x1DWBV+wR/Z1DsI8b05TziqmT+py/PkB0Y/XDRVS2zfIV\nWaSomi3oxaD91FhfcDCAK3ASSnNfizXDs2Q7PdHDQT4pJWnqLMvyZ9DwJpujeEN7GOKqXBiX6SXtXmcS\n-----END CERTIFICATE-----\n"
}
404 Not Found
{
  "errors": [
    {
      "code": "entity_not_found",
      "message": "Certificate with id da39ba51-b556-4a1a-bd78-75e46fa86be7 does not exist"
    }
  ]
}

Path parameters

Name Req/Opt Description
device_id required ID of the device to renew the certificate for.

Request parameters

Name Req/Opt Type Description
csr required string Certificate signing request (CSR).
certificate_profile_attributes defined in certificate profile array Only attributes flagged as "user_provided" are accepted.
.. id - string Certificate attribute ID. See Certificate attributes table below.
.. value - string Label for certificate attribute.
device_attributes defined in enrollment profile array Only attributes from enrollment profile "Source fields" are accepted.
.. id - string ID of custom attribute. Corresponds to source field name in enrollment profile.
.. value - string Label for custom attribute.

Response parameters

Name Type Description
certificate_request_id string Certificate request ID.
status string Request status.
Possible values: PENDING_APPROVAL, APPROVED, AUTO_APPROVED, REJECTED, CANCELED
result string Certificate enrollment status.
Possible values: SUCCESS, FAILED
certificate_id string Certificate ID (only available for SUCCESS status).
pem string Certificate and available intermediate certificates.

Certificate attributes

Certificate attribute ID Description
signature_algorithm Signature algorithm
subject.common_name Common name
subject.organization_name Organization name
subject.organization_unit Organization unit
subject.country Country
subject.state State
subject.locality Locality
subject.street_address Street address
subject.postal_code Postal code
subject.email Email
validity.duration_unit Validity period units
validity.duration_value Validity period value