To create a new private key, you have to POST the private key as a JSON object to the https://<IP-address-of-SPS>/api/private_keys 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 private key in its key attribute. You can reference this ID in other parts of the configuration. Note that you can use a private-key object for only one purpose, that is, you cannot reference one object twice.

URL

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

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

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

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

Table 5: Headers

Header name	Description	Required	Values
Content-Type	Specifies the type of the data sent. SPS uses the JSON format	Required	application/json
session_id	Contains the authentication token of the user	Required	The value of the session ID cookie received from the REST server in the authentication response, for example, a1f71d030e657634730b9e887cb59a5e56162860. For details on authentication, see Authenticate to the SPS REST API.

Sample request

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

• The key must be in PKCS-1 or PKCS-8 PEM format.

• Encrypted private keys are not supported.

• The body of the POST message must be the private key as a single line, enclosed in double-quotes.

• Replace line-breaks in the PEM file with \n

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

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

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

Element		Type	Description
public-key-fingerprint		string	The fingerprint of the public key that matches the private key.
	digest	string	The fingerprint of the key, for example 2048 SHA256:JPKdfkT6wU9c11bbqX53hovDo7KbIB8OREfumUWDh9f no comment (RSA)
	hash_algorithm	string	The hash algorithm used to create the fingerprint, for example, sha256.
type	string	The type of the private key. Must be rsa

Response

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

For details of the meta object, see Message format.

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

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

{
    "body": {
        "public-key-fingerprint": {
            "digest": "2048 SHA256:JPKdfkT6wU9c11bbqX53hovDo7KbIB8OREfumUWDh9f no comment (RSA)",
            "hash_algorithm": "sha256"
        },
        "type": "rsa"
    },
    "key": "6c4d1116-d79d-475b-bb37-9f844f085c14",
    "meta": {
        "first": "/api/configuration/private_keys/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "href": "/api/configuration/private_keys/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "last": "/api/configuration/private_keys/6c4d1116-d79d-475b-bb37-9f844f085c14",
        "next": null,
        "parent": "/api/configuration/private_keys",
        "previous": "/api/configuration/private_keys/e5d13d18-07c5-43fa-89f4-c3d2ece17c71",
        "transaction": "/api/transaction"
    }

Status and error codes

The following table lists the typical status and error codes for this request. For a complete list of error codes, see Application level error codes.

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 and PKCS-8 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 private key

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