This page provides REST endpoint examples for the most common SignServer Client REST API use cases. For a complete reference of endpoints, parameters, and response fields, see REST API Interface.
All examples show the endpoint path relative to the server root of a local SignServer installation at http://localhost:8080. Replace this with your server base URL in production. The examples are tool-agnostic and can be used with any HTTP client, such as cURL, Postman, Python, or JavaScript.
All client requests require:
-
The
X-Keyfactor-Requested-Withheader with a non-empty value, for exampleREST. -
The
Content-Typeheader for requests with a body:application/jsonwhen sending data in a JSON body, ormultipart/form-datawhen uploading files.
All signing responses return a JSON object with the fields described in Response Fields. If a request fails, SignServer returns an error message with the cause of the failure.
Client REST Endpoint Overview
|
Request |
Functionality |
|---|---|
|
POST |
Sign arbitrary data. |
|
POST |
Sign data by providing a certificate ID. |
|
POST |
Sign data by providing a Public Key ID. |
|
POST |
Upload a file. |
|
Perform client-side hashing. |
|
|
GET |
Get the public key from a specific Worker. |
|
GET |
Get the public key from a specific Worker by public key ID. |
|
GET |
Get public keys from all Workers. |
|
GET |
Get the certificate chain from a specified Worker. |
|
GET |
Get the certificate chain from a specified Worker by certificate ID. |
|
GET |
Get certificate chains from all Workers. |
Sign Data
Sign data using the following endpoints. You can also sign data by providing a certificate ID or by providing a Public Key ID.
POST /workers/{idOrName}/process
Use this endpoint to sign arbitrary data. The request body is JSON. The data field accepts a plain string. If you need to send binary data, base64-encode it and set "encoding": "BASE64"
The following example signs data with a Plain Signer:
Request
POST /signserver/rest/v1/workers/{idOrName}/process
Request Body
{
"data": "Sample Data!"
}
Response
{
"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.
POST /rest-managed/v1/workers/{id}/publickeys/{certId}/process
Enterprise
Use this endpoint to sign 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 endpoints.
Request
POST /signserver/rest-managed/v1/workers/{id}/certificates/{certId}/process
Request Body
{
"data": "Sample Data!"
}
Response
{
"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.
POST /rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}/process
Enterprise
Use this endpoint to sign 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.
Request
POST /signserver/rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}/process
Request Body
{
"data": "Sample Data!"
}
Response
{
"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.
Upload a File
POST /workers/{idOrNAme}/process
The following provides an example of uploading and signing a PDF using multipart/form-data, either using cURL or Postman.
The following example uses a PDF Signer and writes the signed output to test_signed.pdf. The PDF is password-protected, so the password is passed as request metadata.
Request
POST /signserver/rest/v1/workers/{idOrName}/process
Request Headers
Set the Accept header to application/octet-stream. This tells SignServer to return the signed file as binary output rather than a JSON response.
The Accept: application/octet-stream header tells SignServer to return the signed file as binary output rather than a JSON response. Omit --output and the Accept header if your signer returns a JSON response.
Request Body
Set the following fields in the request body for uploading and signing a PDF using the Content-Type header multipart/form-data:
|
Form field |
Type |
Value |
|---|---|---|
|
|
File |
The file to sign, for example |
|
|
Text |
The PDF password, if the PDF is password-protected. Additional request metadata properties can be provided the same way, prefixed with |
Response
The response body contains the signed file as binary output. Save the response to a file, for example test_signed.pdf.
To verify the signed PDF, open it in a PDF reader that validates signatures, such as Adobe Acrobat.
Client-side Hashing
POST /workers/{idOrName}/process
Client-side hashing lets you compute the hash of your data locally and send only the hash to SignServer for signing. This is useful when you do not want to transmit the full artifact. For more information, see Client-side Hashing.
The Worker must be configured 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.
The following properties must be provided as request metadata:
|
Property |
Value |
|---|---|
|
|
|
|
|
The hash algorithm used to digest data, for example |
Step 1 - Compute the Hash Locally
For client-side hashing, the encoding of the data needs to be set to BASE64, and the data needs to be a base64-encoded binary.
"encoding": "BASE64"
Example for formatting data:
echo -n "test"| openssl sha256 -binary | base64
8sobtsfpB9Btr+Roflefznazfk6Tt2BQItpS5szCb9I=
Step 2 - Send the Hash for Signing
Example of a request for a Signer using client-side hashing:
{
"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:
{
"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="
}
Step 3 - Verify the Signature
Example for verifying:
$ 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
If the request fails, SignServer returns an error message with the cause of the failure.
Get Public Keys
Public keys can be retrieved:
GET /rest-managed/v1/workers/{IdOrName}/publickeys
Enterprise
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.
Request
Example of a request retrieving a public key from a Worker:
GET /signserver/rest-managed/v1/workers/{idOrName}/publickeys
Response
{
"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 /rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}
Enterprise
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.
Request
Example of a request retrieving a Public Key from a Worker by Public Key ID:
GET /signserver/rest-managed/v1/workers/{idOrName}/publickeys/{publicKeyId}
Response
{
"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 /rest-managed/v1/workers/publickeys
Enterprise
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.
Request
Example of a request retrieving all public keys:
GET /signserver/rest-managed/v1/workers/publickeys
Response
Example of response where two Workers have the CLIENT_VISIBLE Worker property set to true:
{
"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 Certificates
Certificates can be retrieved:
To be able to request one or more certificates, the Worker must be configured with CLIENT_VISIBLE set to true.
Endpoints resolve the certificate chain using the following order of precedence:
-
If the Worker has a
SIGNERCERTCHAINproperty configured, the endpoint returns that chain exclusively. Certificates stored in the Crypto Token are ignored. -
If
SIGNERCERTCHAINis 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 byDEFAULTKEY.
GET /rest-managed/v1/workers/{idOrName}/certificates
Enterprise
This endpoint retrieves the certificate chain from a specified Worker.
Request
GET /signserver/rest-managed/v1/workers/{idOrName}/certificates
Response
{
"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 /rest-managed/v1/workers/{idOrName}/certificates/{certId}
Enterprise
This endpoint retrieves the certificate chain from a specified Worker by certificate ID.
Request
GET /signserver/rest-managed/v1/workers/{idOrName}/certificates/{certId}
Response
{
"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 /rest-managed/v1/workers/certificates
Enterprise
This endpoint retrieves certificate chains from all Workers.
Request
GET /signserver/rest-managed/v1/workers/certificates
Response
{
"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"
}
]
}