To create a new certificate, you have to POST the certificate and its private key as a JSON object to the https://<IP-address-of-SPS>/api/x509 endpoint. For details, see Create a new object. The body of the POST request must contain a JSON object with the parameters listed in Element . The response to a successful POST message is a JSON object that includes the reference ID of the created certificate in its key attribute. You can reference this ID in other parts of the configuration. Note that you can use a certificate object for only one purpose, that is, you cannot reference one object twice.

URL

POST https://<IP-address-of-SPS>/api/configuration/x509

• Note that the GET method is not permitted on this endpoint, you cannot list the existing certificates. However, if you know the reference ID of a certificate, you can display its properties:

  GET https://<IP-address-of-SPS>/api/configuration/x509/<reference-ID-of-the-private-key;>

• You cannot directly delete or modify a certificate, the DELETE and PUT methods are not permitted on certificate objects. To update a certificate, create a new one, then update the object that uses the old certificate to reference the new certificate.

Sample request

The following command creates a new certificate object. Note the following requirements:

curl -X POST -H "Content-Type: application/json" --cookie cookies https://<IP-address-of-SPS>/api/configuration/x509 --data '{"private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END RSA PRIVATE KEY-----\n"}'

The body should be:

{
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END CERTIFICATE-----",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END RSA PRIVATE KEY-----",
    "issuer_chain": []
}

Element		Type	Description
certificate		string	The certificate in PKCS-1 PEM format (replace line-breaks with \n). For example: -----BEGIN CERTIFICATE-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END CERTIFICATE-----
	private_key	string	The private key of the certificate, without encryption or password protection (replace line-breaks with \n). For example: -----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAu3QMMhqeg9ZMLNfdvQoNN1deVRE2SR0VKY+ALnzPZF4fUoJy\n.....\nI2SchDibk/Xj/ZvuEQ23LvzayWOVVuVHtH3JZX3SU4Sa0vpaeC+3oddVTwQOWRq0\n ......... Qbn5W3xKz4vXDDQHEbEsvDQ9A7+uCEuHpO4s33IK9KEa0Zdp745AU0DSGXN4HFzc\n-----END RSA PRIVATE KEY-----
	issuer_chain	list	A comma-separated list of the Certificate Authority (CA) certificates that can be used to validate the uploaded certificate.

Querying a specific key returns the following information about the key:

curl --cookie cookies https://<IP-address-of-SPS>/api/configuration/x509/<reference-ID-of-the-private-key;>

Element		Type	Description
fingerprint		string	The fingerprint of the certificate.
	digest	string	The fingerprint of the certificate, for example ef:d3:8e:d0:81:4f:a2:8f:3b:8b:0c:dd:c7:8f:8c:7e
	hash_algorithm	string	The hash algorithm used to create the fingerprint, for example, sha256.
subject	string	The subject string of the certificate.

Response

The response to a successful POST message is a JSON object that includes the reference ID of the created certificate in its key attribute.

{
    "key": "faa96916-c85e-46ff-8697-f4cc5e596e7f",
    "meta": {
        "href": "/api/configuration/x509/faa96916-c85e-46ff-8697-f4cc5e596e7f",
        "parent": "/api/configuration/x509",
        "transaction": "/api/transaction"
    }
}

The response to querying a specific certificate is a JSON object that includes the parameters of the certificate, for example:

{
    "body": {
        "fingerprint": {
            "digest": "ef:d3:8e:d0:81:4f:a2:8f:3b:8b:0c:dd:c7:8f:8c:7e",
            "hash_algorithm": "md5"
        },
        "subject": "C=RO/ST=State/L=Locality/O=Organization/OU=OrganizationalUnit/CN=example.com/emailAddress=root@example.com"
    },
    "key": "6c4d1116-d79d-475b-bb37-9f844f085c14",
    "meta": {
        "first": "/api/configuration/x509/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "href": "/api/configuration/x509/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "last": "/api/configuration/x509/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "next": null,
        "parent": "/api/configuration/x509",
        "previous": "/api/configuration/x509/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "transaction": "/api/transaction"
    }

Code	Description	Notes
201	Created	The new resource was successfully created.
400	SyntacticError	Syntax error: Could not load PEM key: Unsupported private key format, only PKCS-1 is supported. Encrypted private keys are not supported.
401	Unauthenticated	The requested resource cannot be retrieved because the client is not authenticated and the resource requires authorization to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
403	Unauthorized	The requested resource cannot be retrieved because the client is not authorized to access it. The details section contains the path that was attempted to be accessed, but could not be retrieved.
404	NotFound	The requested object does not exist.
405	MethodNotAllowed	The method <method> is not allowed for this node.

Modify or delete certificate

You cannot directly delete or modify a certificate, the DELETE and PUT methods are not permitted on certificate objects. To update a certificate, create a new one, then update the object that uses the old certificate to reference the new certificate. After you commit the transaction, SPS will automatically delete the old certificate.