Client REST Interface | Keyfactor Docs

The SignServer REST Interface supports integration with SignServer, providing an OpenAPI specification and more options for request and response formats, including JSON. This is a RESTful alternative to the Client HTTP Interface.

For the configuration and administration of REST, see Admin REST Interface.

Use Postman REST Endpoints for Signing

Signing Request

Endpoint: POST /workers/{idOrName}/process

Example of simple body only data to be signed with a Plain Signer:

JSON

{
  "data": "Sample Data!"
}

Response from a PlainSigner:

JSON

{
    "archiveId": "022a0fee43ba76ed26605cc87c090afb9ea66b07",
    "data": "P2TkMBhhwDGfu9OUarAf65Z2h2gkDYqiQGV6WPi+N6mdxxbi8g14k+BvCz47yhDAVD3D/bJhP+L5knYQ92rgfcf7AS2o2o7ppzCE0ZvEtY0mZHL/7GAe4ZnuK+8cqeK1kP9mY9/dIWsZelZb8LPLVsC/rdFBAW89LsGzvjw6mEK1Zle4JkkqM7K+c1bnOYWYaLxIXTgxgPz6i9ccMoYREUntZ0srf2rKcv1k1W0/kc8G0R3CjC8Hje/J+FpIAOtd89kG4nvqa/OPt8GqipnXAmPXpCOuDAvDsWEJL32x+QHqdkl4ixaeAxFWnougm/qL0MZF6KmYXXm/wXqTD2o6pA==",
    "metaData": {},
    "requestId": "-1361181487",
    "signerCertificate": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhcwDQYJKoZIhvcNAQELBQAwTDEWMBQGA1UEAwwNRFNTIFN1YiBDQSAxMTEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwHhcNMTYwMzAzMDgyNTA0WhcNMzYwMjI3MDgyNTA0WjBKMRQwEgYDVQQDDAtzaWduZXIwMDAwMzEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCyFKqwwiHS2o4PO3zovqC+jGuIELnja1iAlg/hyrRp28mF6BOGVaKE6ZzbQIMmmICRz+EeqXN1W8gyCEh6T2qN3QvXTAF9mrrUI3hG4Xn/Davgsln8saRE0zt45yy47dPq5YofYJWWIdW/6qssiX+ApcPqthCQfkgraUSagS/Reqy0WT/A2lwKh147GB9+MxhheskQIPaKQasOpI7vGfzey+GnkHPsfU21irS2nC8uzv6hd0G6hNYUEmJtIh9/5WebMoMiGFq1sydTtZp7pJilfPyxrAkHXEwMUEEMcVlE/ISCoKMttnLMUT/F00cHesU4D2yNl6gcSjpMj4Q/iF+hAgMBAAGjfzB9MB0GA1UdDgQWBBQ2/WY3Ln7tdUmDrTyvtvSZwBg8YzAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFBxgQUremK3l1gOK6GaCqX6w8gKHMA4GA1UdDwEB/wQEAwIF4DAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwDQYJKoZIhvcNAQELBQADggEBAIUh6kkCMc0Fs6U+Sw6Ns0Yd28Fb5SM//nE6mq3mf1SD4lAyChVrFvlqMZJaqeJlkVeHc9E+KCE5bX1r2iGC8rnE9DuItI0pKMrgFt4cbSbDwgovnTrkiIhuqP2pjdhmrHtlLqZBR8e16c4xGSn6XWKJ8vPzx2AJl7MY3sY3Z4aPckBFNjG1lzH1inq5WM/+WaLghOQQngaXeU+SWpoAM7cUjB8Uyjf2Qr2GerI4AZZJMuC6BuvMdFMyXX78l7c9qmvK9Bre+SFKdtcMAgnglLzu0lyPHPwYL0R+pwc5dFOJipafxeqeHGpkZTXMsdMn6f1USRznlGbRWru68/XOOFU="
}

Client-side Hashing

Endpoint: POST /workers/{IDorName}/process

For more information on client-side hashing, see Client-side Hashing.

Make sure to configure the Signer to accept a hash as input by setting CLIENTSIDEHASHING=TRUE, or by allowing the client to specify if the input is the original file or a hash of it, by configuring ALLOW_CLIENTSIDEHASHING_OVERRIDE=TRUE.

When the client sends the request, the following properties need to be provided as request metadata:

USING_CLIENTSUPPLIED_HASH=true
CLIENTSIDE_HASHDIGESTALGORITHM=SHA-256

Replace “SHA-256” with the name of the hash algorithm used to digest the data. The algorithm must be one of those configured in the signer with the ACCEPTED_HASH_DIGEST_ALGORITHMS property.

For client-side hashing, the encoding of the data needs to be set to BASE64, and the data needs to be base64 encoded binary.

  "encoding": "BASE64"

Example for formatting data:

Bash

echo -n "test"| openssl sha256 -binary | base64
8sobtsfpB9Btr+Roflefznazfk6Tt2BQItpS5szCb9I=

Example of body for a Signer using client-side hashing:

JSON

{
  "metaData": {
    "USING_CLIENTSUPPLIED_HASH":"true",
    "CLIENTSIDE_HASHDIGESTALGORITHM":"SHA256"
  },
  "encoding": "BASE64",
  "data": "8sobtsfpB9Btr+Roflefznazfk6Tt2BQItpS5szCb9I="
}

If the request is successful, SignServer returns status 200 OK with the following response body:

JSON

{
    "archiveId": "61f5414b202a8c4006a1f9e7486af0181f73d710",
    "data": "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",
    "metaData": {},
    "requestId": "457529920",
    "signerCertificate": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhcwDQYJKoZIhvcNAQELBQAwTDEWMBQGA1UEAwwNRFNTIFN1YiBDQSAxMTEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwHhcNMTYwMzAzMDgyNTA0WhcNMzYwMjI3MDgyNTA0WjBKMRQwEgYDVQQDDAtzaWduZXIwMDAwMzEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCyFKqwwiHS2o4PO3zovqC+jGuIELnja1iAlg/hyrRp28mF6BOGVaKE6ZzbQIMmmICRz+EeqXN1W8gyCEh6T2qN3QvXTAF9mrrUI3hG4Xn/Davgsln8saRE0zt45yy47dPq5YofYJWWIdW/6qssiX+ApcPqthCQfkgraUSagS/Reqy0WT/A2lwKh147GB9+MxhheskQIPaKQasOpI7vGfzey+GnkHPsfU21irS2nC8uzv6hd0G6hNYUEmJtIh9/5WebMoMiGFq1sydTtZp7pJilfPyxrAkHXEwMUEEMcVlE/ISCoKMttnLMUT/F00cHesU4D2yNl6gcSjpMj4Q/iF+hAgMBAAGjfzB9MB0GA1UdDgQWBBQ2/WY3Ln7tdUmDrTyvtvSZwBg8YzAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFBxgQUremK3l1gOK6GaCqX6w8gKHMA4GA1UdDwEB/wQEAwIF4DAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwDQYJKoZIhvcNAQELBQADggEBAIUh6kkCMc0Fs6U+Sw6Ns0Yd28Fb5SM//nE6mq3mf1SD4lAyChVrFvlqMZJaqeJlkVeHc9E+KCE5bX1r2iGC8rnE9DuItI0pKMrgFt4cbSbDwgovnTrkiIhuqP2pjdhmrHtlLqZBR8e16c4xGSn6XWKJ8vPzx2AJl7MY3sY3Z4aPckBFNjG1lzH1inq5WM/+WaLghOQQngaXeU+SWpoAM7cUjB8Uyjf2Qr2GerI4AZZJMuC6BuvMdFMyXX78l7c9qmvK9Bre+SFKdtcMAgnglLzu0lyPHPwYL0R+pwc5dFOJipafxeqeHGpkZTXMsdMn6f1USRznlGbRWru68/XOOFU="
}

If the request fails, it will return an error message with the cause of the failure.
An example of what a failure could look like is, status 400 Bad Request with response body "error": "Client-side hashing requested but not allowed", for trying to use a CMS Signer that has ALLOW_CLIENTSIDEHASHING_OVERRIDE set to false or using default value which is also false.

File Upload

Endpoint: POST /workers/{idOrName}/process

To use the file upload endpoint:

Change the Header Accept from default value */* to application/octet-stream. This is found under Header in Postman.
Set the body input type to form-data to provide a file instead a body.
Choose file in the drop down for input type and browse for the file you would like to provide for signing.

If the request is successful, SignServer returns status 200 OK with a response body with the file you signed.

If the request fails, SignServer returns an error message with the cause of the failure.
For example, if you try to use a PDF Signer but you provided a file that is not a PDF, the failure shows 400 Bad Request with response body:

"error": "Could not sign document: PDF header signature not found."

Use cURL REST Endpoints for Signing

Signing Request

Endpoint: POST /workers/{idOrName}/process

The following provides an example of signing some sample data.

Example of a request:

Bash

curl --location --request POST 'http://localhost:8080/signserver/rest/v1/workers/{idOrName}/process' \
--header 'X-Keyfactor-Requested-With: X' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": "Sample Data!"
}'

Response:

JSON

{
  "archiveId":"12aab5dba45d5fbe538a1d210287ae4912df677b",
  "data":"P2TkMBhhwDGfu9OUarAf65Z2h2gkDYqiQGV6WPi+N6mdxxbi8g14k+BvCz47yhDAVD3D/bJhP+L5knYQ92rgfcf7AS2o2o7ppzCE0ZvEtY0mZHL/7GAe4ZnuK+8cqeK1kP9mY9/dIWsZelZb8LPLVsC/rdFBAW89LsGzvjw6mEK1Zle4JkkqM7K+c1bnOYWYaLxIXTgxgPz6i9ccMoYREUntZ0srf2rKcv1k1W0/kc8G0R3CjC8Hje/J+FpIAOtd89kG4nvqa/OPt8GqipnXAmPXpCOuDAvDsWEJL32x+QHqdkl4ixaeAxFWnougm/qL0MZF6KmYXXm/wXqTD2o6pA==",
  "metaData":{},
  "requestId":"1277380144",
  "signerCertificate":"MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc..."
}

If the request fails, SignServer returns an error message with the cause of the failure.

Signing Request by Certificate ID

Enterprise

Endpoint: POST /rest-managed/v1/workers/{id}/publickeys/{certId}/process

The following example shows how to sign some arbitrary data by providing a Certificate ID. SignServer takes the certificate ID and compares it to the signing certificate ID from SIGNERCERTCHAIN Worker property, or from the Crypto Token if SIGNERCERTCHAIN is not present. If the IDs match, SignServer proceeds with signing the data.

Certificate ID can be retrieved using the Get Certificates endpoint.

Example of a request:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/{id}/certificates/{certId}/process' \
--header 'X-Keyfactor-Requested-With: 0' \
--header 'Content-Type: application/json' \
--data '{
    "data": "Sample Data!"
}'

Response:

JSON

{
    "archiveId": "67ab62c6638d6bfcf2e0f5535440abe324005aca",
    "data": "eG5Nql59LVOo1tW2C0VUp7LIdxvqbKr3wD7gGf7XHlW1WC/1wkHY6t8uxomUutg42RBuaKU3Qa0NJsI29j0veP+4ptBhaLVTX4x/pIQynaJm40Jv0+VRbP18pLsTYfVh9Xwnn1Jn5f5XKEsZkZHws2G1ycBMGVt/HDx3kV5qlv7tA6CVC+5x9s6a4wYR5AvrgFJAQa/TPU4NPHPBplDLZ5BpmqU0NuLoBpuc3NERi/kMco+tNLQ/awPmYYFYCB1/EDUb0euUt1gYQSH6BtmfTV825T6gClGiwvPFfYEx8GCntMxygfEr97qcVCl65kE/c2nXqqeWp7kzPml7F7SXlA==",
    "metaData": {},
    "requestId": "542982616",
    "signerCertificate": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc..."
}

If the request fails, SignServer returns an error message with the cause of the failure.

Signing Request by Public Key ID

Enterprise

Endpoint: POST /rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}/process

The following example shows how to sign some arbitrary data by providing a Public Key ID. SignServer takes the Public Key ID and compares it with the public key from the key specified in DEFAULTKEY Worker property. If the IDs match, SignServer proceeds with signing the data.

Public Key ID can be retrieved using the Get Public Key endpoint.

Example of a request:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}/process' \
--header 'X-Keyfactor-Requested-With: 0' \
--header 'Content-Type: application/json' \
--data '{
    "data": "hello"
}'

Response:

JSON

{
    "archiveId": "501bfa7035914e75fdab360481f5e62d5e33f3af",
    "data": "eG5Nql59LVOo1tW2C0VUp7LIdxvqbKr3wD7gGf7XHlW1WC/1wkHY6t8uxomUutg42RBuaKU3Qa0NJsI29j0veP+4ptBhaLVTX4x/pIQynaJm40Jv0+VRbP18pLsTYfVh9Xwnn1Jn5f5XKEsZkZHws2G1ycBMGVt/HDx3kV5qlv7tA6CVC+5x9s6a4wYR5AvrgFJAQa/TPU4NPHPBplDLZ5BpmqU0NuLoBpuc3NERi/kMco+tNLQ/awPmYYFYCB1/EDUb0euUt1gYQSH6BtmfTV825T6gClGiwvPFfYEx8GCntMxygfEr97qcVCl65kE/c2nXqqeWp7kzPml7F7SXlA==",
    "metaData": {},
    "requestId": "863468954",
    "signerCertificate": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc..."
}

If the request fails, SignServer returns an error message with the cause of the failure.

Client-side Hashing

Endpoint: POST /workers/{idOrName}/process

The following provides an example of signing some sample data with client-side hashing. For more information, see Client-side Hashing.

When the client sends the request, the following properties need to be provided as request metadata:

USING_CLIENTSUPPLIED_HASH=true
CLIENTSIDE_HASHDIGESTALGORITHM=SHA-256

In CLIENTSIDE_HASHDIGESTALGORITHM=SHA-256, replace SHA-256 with the name of the hash algorithm used to digest the data. The algorithm must be one of those configured in the signer with the ACCEPTED_HASH_DIGEST_ALGORITHMS property.

For client-side hashing, the encoding of the data needs to be set to BASE64, and the data needs to be base64 encoded binary.

Example for formatting data:

Bash

$ echo "Sample" > sample.txt
$ openssl dgst -sha256 -out pre-computed-hash.bin -binary sample.txt
$ base64 pre-computed-hash.bin
47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

Example of a request for a Signer using client-side hashing:

Bash

$ curl --location --request POST 'http://localhost:8080/signserver/rest/v1/workers/{idOrName}/process' \
--header 'X-Keyfactor-Requested-With: X' \
--header 'Content-Type: application/json' \
--data-raw '{
    "metaData": {
        "CLIENTSIDE_HASHDIGESTALGORITHM": "SHA-256",
        "USING_CLIENTSUPPLIED_HASH": "true"
    },
    "data": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
    "encoding": "BASE64"
}'

Response:

JSON

{
   "archiveId":"bdce6dbdfeb4207979ac5047e000da6aaa1085ad",
   "data":"Eb/2MbFLQR0kSJ0uUveIdP6qF8xwaphpHbm4yFZDM9NmekMl1TMvCEh7E9sipFTWfhC97b5BtOyQLH6tucwz8j9VD+b534uhvpkwTOjbSkDpAzgTsmfXLlzaOt8/X8/HbYpr+RTQQPXM2pGEc7s8OxqnQetAU7aadPXDHPN14C71oGTGVDn6tLMlSgOhPL2L3d8qKAlWlxEJPhInLA4BwyOuJ7X45dpJS2rO0sKRyHWS1T+z1cHf41hDvlTaX9xmYiYkNC9s0kwV4xwBNjGebs2I0vtHVT/99l47/sj/vCk191IDPupfrtAMHpBo3EMsuuLn0xbVkI0Tkil4Emrp6A==",
   "metaData":{},
   "requestId":"465995014",
   "signerCertificate":"MIIDlzCCAn+gAwIBAgIIOdPbElQbJhcwDQYJKoZIhvcNAQELBQAwTDEWMBQGA1UEAwwNRFNTIFN1YiBDQSAxMTEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwHhcNMTYwMzAzMDgyNTA0WhcNMzYwMjI3MDgyNTA0WjBKMRQwEgYDVQQDDAtzaWduZXIwMDAwMzEQMA4GA1UECwwHVGVzdGluZzETMBEGA1UECgwKU2lnblNlcnZlcjELMAkGA1UEBhMCU0UwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCyFKqwwiHS2o4PO3zovqC+jGuIELnja1iAlg/hyrRp28mF6BOGVaKE6ZzbQIMmmICRz+EeqXN1W8gyCEh6T2qN3QvXTAF9mrrUI3hG4Xn/Davgsln8saRE0zt45yy47dPq5YofYJWWIdW/6qssiX+ApcPqthCQfkgraUSagS/Reqy0WT/A2lwKh147GB9+MxhheskQIPaKQasOpI7vGfzey+GnkHPsfU21irS2nC8uzv6hd0G6hNYUEmJtIh9/5WebMoMiGFq1sydTtZp7pJilfPyxrAkHXEwMUEEMcVlE/ISCoKMttnLMUT/F00cHesU4D2yNl6gcSjpMj4Q/iF+hAgMBAAGjfzB9MB0GA1UdDgQWBBQ2/WY3Ln7tdUmDrTyvtvSZwBg8YzAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFBxgQUremK3l1gOK6GaCqX6w8gKHMA4GA1UdDwEB/wQEAwIF4DAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwDQYJKoZIhvcNAQELBQADggEBAIUh6kkCMc0Fs6U+Sw6Ns0Yd28Fb5SM//nE6mq3mf1SD4lAyChVrFvlqMZJaqeJlkVeHc9E+KCE5bX1r2iGC8rnE9DuItI0pKMrgFt4cbSbDwgovnTrkiIhuqP2pjdhmrHtlLqZBR8e16c4xGSn6XWKJ8vPzx2AJl7MY3sY3Z4aPckBFNjG1lzH1inq5WM/+WaLghOQQngaXeU+SWpoAM7cUjB8Uyjf2Qr2GerI4AZZJMuC6BuvMdFMyXX78l7c9qmvK9Bre+SFKdtcMAgnglLzu0lyPHPwYL0R+pwc5dFOJipafxeqeHGpkZTXMsdMn6f1USRznlGbRWru68/XOOFU="
}

If the request fails, SignServer returns an error message with the cause of the failure.

Example for verifying:

Bash

$ echo Eb/2MbFLQR0kSJ0uUveIdP6qF8xwaphpHbm4yFZDM9NmekMl1TMvCEh7E9sipFTWfhC97b5BtOyQLH6tucwz8j9VD+b534uhvpkwTOjbSkDpAzgTsmfXLlzaOt8/X8/HbYpr+RTQQPXM2pGEc7s8OxqnQetAU7aadPXDHPN14C71oGTGVDn6tLMlSgOhPL2L3d8qKAlWlxEJPhInLA4BwyOuJ7X45dpJS2rO0sKRyHWS1T+z1cHf41hDvlTaX9xmYiYkNC9s0kwV4xwBNjGebs2I0vtHVT/99l47/sj/vCk191IDPupfrtAMHpBo3EMsuuLn0xbVkI0Tkil4Emrp6A==
    | base64 --decode > sample.sig
$ openssl dgst -signature sample.sig -verify plainsigner-pubkey.pem -SHA256 sample.txt
Verified OK

File Upload

Endpoint: POST /workers/{idOrNAme}/process

The following provides an example of uploading and signing a PDF using multipart/form-data.

In this example, a password-protected PDF is signed to also display how to properly set additional request metadata properties that will be sent to the PDF Signer.

Example for uploading and signing a PDF:

Bash

curl --output test_signed.pdf --location --request POST 'http://localhost:8080/signserver/rest/v1/workers/{idOrName}/process' \
--header 'X-Keyfactor-Requested-With: REST' \
--header 'Accept: application/octet-stream' \
--form 'myfile=@"test.pdf"' \
--form 'REQUEST_METADATA.pdfPassword="foo123";type=multipart/form-data;charset=utf-8'

Use REST Endpoints to Retrieve Keys & Certificates

Get Public Key by Worker Name or ID

Enterprise

Endpoint: GET /rest-managed/v1/workers/{IdOrName}/publickeys

Get the public key from a specific Worker. The key to retrieve is specified in the DEFAULTKEY Worker property on the Worker. To request a public key, the Worker must be configured with CLIENT_VISIBLE set to true.

Example of a request retrieving a public key from a Worker:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/{idOrName}/publickeys' \
--header 'X-Keyfactor-Requested-With: 1'

Response:

JSON

{
  "workerPublicKey": [
    {
      "entries": [
        {
          "keyType": "X.509",
          "links": {
            "process": "/workers/1/publickeys/38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200/process",
            "public key": "/workers/1/publickeys/38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200"
          },
          "publicKey": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc...",
          "publicKeyId": "38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200"
        }
      ],
      "workerId": "1",
      "workerName": "PlainSigner"
    }
  ]
}

Get Public Key by Public Key ID

Enterprise

Endpoint: GET /rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}

Get the public key from a specific Worker by public key ID. The key to retrieve is specified in the DEFAULTKEY Worker property on the Worker. To request a public key, the Worker must be configured with CLIENT_VISIBLE set to true.

Example of a request retrieving a Public Key from a Worker by Public Key ID:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}' \
--header 'X-Keyfactor-Requested-With: 1'

Response:

JSON

{
  "workerPublicKey": [
    {
      "entries": [
        {
          "keyType": "X.509",
          "links": {
            "process": "/workers/1/publickeys/38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200/process",
            "public key": "/workers/1/publickeys/38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200"
          },
          "publicKey": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc...",
          "publicKeyId": "38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200"
        }
      ],
      "workerId": "1",
      "workerName": "PlainSigner"
    }
  ]
}

Get Public Keys

Enterprise

Endpoint: GET /rest-managed/v1/workers/publickeys

Get public keys from all Workers. The keys to retrieve are specified in the DEFAULTKEY Worker property on the Workers. The Workers must be configured with CLIENT_VISIBLE set to true.

Example of a request retrieving all public keys:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/publickeys' \
--header 'X-Keyfactor-Requested-With: 1'

Example of response where two Workers have the CLIENT_VISIBLE Worker property set to true:

JSON

{
    "workerPublicKey": [
        {
            "entries": [
                {
                    "keyType": "X.509",
                    "links": {
                        "process": "/workers/1/publickeys/38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200/process",
                        "public key": "/workers/1/publickeys/38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200"
                    },
                    "publicKey": "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc...",
                    "publicKeyId": "38a45dca26a72034547985b7ef07376e1bd8c38225b7cb864a90843456991200"
                }
            ],
            "workerId": "1",
            "workerName": "PlainSigner"
        },
        {
            "entries": [
                {
                    "keyType": "PGP",
                    "links": {
                        "process": "/workers/2/publickeys/b3b97913343031fd10b8fa1d5d9df87cbe92a3806ef0fcee53c655339d286e3a/process",
                        "public key": "/workers/2/publickeys/b3b97913343031fd10b8fa1d5d9df87cbe92a3806ef0fcee53c655339d286e3a"
                    },
                    "publicKey": "mQENBFbX9OABCACyFKqwwiHS2o4PO3z...",
                    "publicKeyId": "b3b97913343031fd10b8fa1d5d9df87cbe92a3806ef0fcee53c655339d286e3a"
                }
            ],
            "workerId": "2",
            "workerName": "OpenPGPSigner"
        }
    ]
}

Get Certificate by Worker Name or ID

Enterprise

Endpoint: GET /rest-managed/v1/workers/{idOrName}/certificates

This endpoint retrieves the certificate chain from a specified Worker. To be able to request one or more certificates, the Worker must be configured with CLIENT_VISIBLE set to true.

Endpoint resolves the certificate chain using the following order of precedence:

If the Worker has a SIGNERCERTCHAIN property configured, the endpoint returns that chain exclusively. Certificates stored in the Crypto Token are ignored.
If SIGNERCERTCHAIN is not present in the Worker configuration, the endpoint falls back to retrieving the certificate chain directly from the token (HSM), based on the key referenced by DEFAULTKEY.

Example request of retrieving certificate chain from one Worker:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/{idOrName}/certificates' \
--header 'X-Keyfactor-Requested-With: 1'

Example response:

JSON

{
    "workerCertificate": [
        {
            "base64CertChain": [
                "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc...",
                "MIIEfjCCAmagAwIBAgIINRnImL/vDX4...",
                "MIIFfzCCA2egAwIBAgIIMk1BOK8CwTw..."
            ],
            "certId": "95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2",
            "links": {
                "process": "/workers/1/certificates/95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2/process",
                "certificate": "/workers/1/certificates/95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2"
            },
            "workerId": "1",
            "workerName": "PlainSigner"
        }
    ]
}

Get Certificate by Certificate ID

Enterprise

Endpoint: GET /rest-managed/v1/workers/{idOrName}/certificates/{certId}

This endpoint retrieves the certificate chain from a specified Worker by certificate ID. To be able to request one or more certificates, the Worker must be configured with CLIENT_VISIBLE set to true.

Endpoint resolves the certificate chain using the following order of precedence:

If the Worker has a SIGNERCERTCHAIN property configured, the endpoint returns that chain exclusively. Certificates stored in the Crypto Token are ignored.
If SIGNERCERTCHAIN is not present in the Worker configuration, the endpoint falls back to retrieving the certificate chain directly from the token (HSM), based on the key referenced by DEFAULTKEY.

Example request of retrieving the certificate chain from one Worker:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/{idOrName}/certificates/{certId}' \
--header 'X-Keyfactor-Requested-With: 1'

Example response:

JSON

{
    "workerCertificate": [
        {
            "base64CertChain": [
                "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc...",
                "MIIEfjCCAmagAwIBAgIINRnImL/vDX4...",
                "MIIFfzCCA2egAwIBAgIIMk1BOK8CwTw..."
            ],
            "certId": "95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2",
            "links": {
                "process": "/workers/1/certificates/95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2/process",
                "certificate": "/workers/1/certificates/95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2"
            },
            "workerId": "1",
            "workerName": "PlainSigner"
        }
    ]
}

Get Certificates

Enterprise

Endpoint: GET /rest-managed/v1/workers/certificates

This endpoint retrieves certificate chains from all Workers. To be able to request one or more certificates, the Worker must be configured with CLIENT_VISIBLE set to true.

Endpoint resolves the certificate chain using the following order of precedence:

If the Worker has a SIGNERCERTCHAIN property configured, the endpoint returns that chain exclusively. Certificates stored in the Crypto Token are ignored.
If SIGNERCERTCHAIN is not present in the Worker configuration, the endpoint falls back to retrieving the certificate chain directly from the token (HSM), based on the key referenced by DEFAULTKEY.

Example request of retrieving certificate chain from one Worker:

Bash

curl --location 'http://localhost:8080/signserver/rest-managed/v1/workers/certificates' \
--header 'X-Keyfactor-Requested-With: 1'

Example response:

JSON

{
    "workerCertificate": [
        {
            "base64CertChain": [
                "MIIDlzCCAn+gAwIBAgIIOdPbElQbJhc...",
                "MIIEfjCCAmagAwIBAgIINRnImL/vDX4...",
                "MIIFfzCCA2egAwIBAgIIMk1BOK8CwTw..."
            ],
            "certId": "95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2",
            "links": {
                "process": "/workers/1/certificates/95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2/process",
                "certificate": "/workers/1/certificates/95bf59ae3f23515f36e02e9a97e41331dfb87dee355460774a24e4d4880688e2"
            },
            "workerId": "1",
            "workerName": "PlainSigner"
        }
    ]
}