POST /staged_config/certificates/root_certificates

Edit online

Uploads a new single root certificate to the staged configuration folder on the Console.

This API enables the deployment of new root certificates to managed hosts, which enables the TLS handshake between a managed host and a destination device.

The following steps are required to push the root certificate to the managed host:
  • Invoke this synchronous endpoint to upload the new single root certificate to the staged configuration folder on the Console.
  • Deploy the changes to push the new root certificate to the managed host.

You must have System Administrator permissions to use this endpoint.

Table 1. POST /staged_config/certificates/root_certificates resource details
MIME Type

application/json

Table 2. POST /staged_config/certificates/root_certificates request parameter details
Parameter Type Optionality Data Type MIME Type Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.
Table 3. POST /staged_config/certificates/root_certificates request body details
Parameter Data Type MIME Type Description Sample

certificate_content

String

text/plain

Required. The contents of a single PEM-encoded x509 root certificate to be uploaded to the Console.

String
Table 4. POST /staged_config/certificates/root_certificates response codes
HTTP Response Code Unique Code Description

200

The certificate has been uploaded.

409

1102

Certificate already exists.

422

1101

The certificate is invalid.

422

2001

Error parsing a certificate

422

2002

Error parsing a certificate

422

2003

The certificate is expired

422

2004

The certificate is not yet valid

422

2005

The certificate is revoked

422

2010

Unexpected error occurred when processing a certificate

422

2011

Error finding issuer certificates

422

2012

The certificate's key usage or extended key usage does not match to its purpose

422

2013

Error validating the full chain of the certificate

422

2014

The certificate is an invalid self-signed certificate

422

2020

The CRL is invalid

422

2030

Unexpected error when processing CRL

422

2031

Error finding the issuer certificates for the CRL

422

2032

The issuer does not have CRL signing authority.

422

2033

Error validating the CRL

422

2034

The CRL is expired

500

1020

for unknown exception error code 500

Response Description

Displays the following information about the certificate resource:
  • id - Uniquely identifies the certificate. This value is derived from subject_key_id.
  • subject_key_id - Returns the Subject Key Identifier of the CA certificate.
  • authority_key_id - Returns the Authority Key Identifier of the CA certificate.
  • subject - Returns the Subject of the CA certificate.
  • issuer - Returns the Issuer of the CA certificate.
  • not_before - Returns the "Validity Not Before" field of the certificate, represented as the number of milliseconds since UNIX epoch.
  • expiry - Returns the "Validity Not After" field of the certificate, represented as the number of milliseconds since UNIX epoch. 
  • serial_number - Returns the "Serial Number" field of the certificate.
  • key_usage - Returns the "Key Usage" field of the certificate. The values are one or more of the enum X509Certificate.KeyUsage
    • CRL_SIGN
    • DATA_ENCIPHERMENT
    • DECIPHER_ONLY
    • DIGITAL_SIGNATURE
    • ENCIPHER_ONLY
    • KEY_AGREEMENT
    • KEY_CERT_SIGN
    • KEY_ENCIPHERMENT
    • NON_REPUDIATION
  • status - Returns the status of the certificate. After you upload the certificate, the value will be DEPLOY_PENDING to indicate that the changes must be deployed.
  • validation - Returns the code to indicate whether the certificate is valid. If not, it returns the reason that the certificate is not valid.
    • 0 - Certificate is valid or has not been checked.
    • 2001 - Error parsing a certificate.
    • 2002 - Error decoding a certificate.
    • 2003 - The certificate is expired.
    • 2004 - The certificate is not yet valid.
    • 2005 - The certificate is revoked.
    • 2010 - An unexpected error occurred when processing a certificate.
    • 2011 - Error finding the issuer certificates.
    • 2012 - The certificate's key usage or extended key usage does not match its purpose.
    • 2013 - Error validating the full chain of the certificate.
    • 2014 - The certificate is an invalid self-signed certificate.
    • 2020 - The CRL is invalid.
    • 2030 - Unexpected error when processing the CRL.
    • 2031 - Error finding the issuer certificates for the CRL.
    • 2032 - The issuer does not have the CRL sign usage.
    • 2033 - Error validating the CRL.
    • 2034 - The CRL is expired.

Response Sample


{
    "authority_key_id": "String",
    "expiry": 42,
    "id": "String",
    "issuer": [
        {
            "field_name": "String",
            "value": "String"
        }
    ],
    "key_usage": [
        "String <one of: CRL_SIGN, DATA_ENCIPHERMENT, DECIPHER_ONLY, DIGITAL_SIGNATURE, ENCIPHER_ONLY, KEY_AGREEMENT, KEY_CERT_SIGN, KEY_ENCIPHERMENT, NON_REPUDIATION>"
    ],
    "not_before": 42,
    "serial_number": "String",
    "status": "String",
    "subject": [
        {
            "field_name": "String",
            "value": "String"
        }
    ],
    "subject_key_id": "String",
    "validation": 42
}