Admin REST Endpoints | Keyfactor Docs

This page provides REST endpoint examples for the most common SignServer Admin REST API use cases. For a complete reference of endpoints, parameters, and response fields, see REST API Interface.

All examples assume a local SignServer installation at https://localhost::8443/signserver. 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 admin requests require:

The X-Keyfactor-Requested-With header with a non-empty value, for example REST.
The Content-Type: application/json header for requests with a JSON body.
A client TLS certificate for an authorized administrator, presented with the request. For examples of how to present the certificate in different environments, see Providing the Client Certificate.

Every request must include the X-Keyfactor-Requested-With header with a non-empty value.

For the REST endpoints for signing and retrieving keys and certificates, see Client REST Endpoints.

Admin REST Endpoint Overview

Request	Functionality
POST `/workers`	Add a Worker.
POST `/workers/{id}`	Add a Worker with a specific ID.
GET `/workers`	Get the ID and name of Workers on the SignServer instance.
GET `/workers/{id}`	Get the detailed configuration of a specific Worker.
PAtch `/workers/{id}`	Change or add a Worker configuration property.
PUT `/workers/{id}`	Overwrite the full configuration of the provided Worker ID.
Delete `/workers/{id}`	Delete the Worker with the provided ID.
POST `/workers/reload`	Reload the configuration from database.

Add New Worker

Adding a new Worker can be done from two endpoints. You can choose to provide a specific ID with {id}. If you do not provide an ID, SignServer sets the next available one for you.

POST /workers or /workers/{id}

The following example creates a Plain Signer.

Request

POST /signserver/rest/v1/workers

cURL

Bash

curl --location --cert dss10_admin1.p12 --cert-type p12 --pass foo123 --request POST 'https://localhost:8443/signserver/rest/v1/workers' \
--header 'X-Keyfactor-Requested-With: X' \
--header 'Content-Type: application/json' \
--data-raw '{
    "properties": {
        "NAME": "PlainSigner",
        "IMPLEMENTATION_CLASS": "org.signserver.module.cmssigner.PlainSigner",
        "TYPE": "PROCESSABLE",
        "AUTHTYPE": "NOAUTH",
        "CRYPTOTOKEN": "CryptoTokenP12",
        "DEFAULTKEY": "signer00003",
        "DISABLEKEYUSAGECOUNTER": "true"
    }
}'

Request Body

JSON

{
   "properties": {
      "NAME":"PlainSigner",
      "IMPLEMENTATION_CLASS":"org.signserver.module.cmssigner.PlainSigner",
      "TYPE":"PROCESSABLE",
      "AUTHTYPE":"NOAUTH",
      "CRYPTOTOKEN":"CryptoTokenP12",
      "DEFAULTKEY":"signer00003",
      "DISABLEKEYUSAGECOUNTER":"true"
   }
}

Response

If the request is successful, SignServer returns status 201 Created. If the request fails, SignServer returns an error message with the cause of the failure.

Get Worker Configuration

You can request the full configuration of all Workers from the SignServer instance or a more detailed configuration for one specific worker ID.

GET /workers

The GET /workers endpoint only returns the ID and name of the existing Workers on the SignServer instance. It does not look at the request body even if one is provided.

Request

GET /signserver/rest/v1/workers

Response

JSON

{
  "workers": [
    {
      "id": 1,
      "name": "CryptoTokenP12"
    },
    {
      "id": 2,
      "name": "PlainSigner"
    }
  ]
}

GET /workers/{id}

The GET /workers/{id} endpoint provides a more detailed configuration of a specified Worker. This endpoint also does not look at the request body even if one is provided.

Request

GET /signserver/rest/v1/workers/{id}

Response

Example response for the provided ID pointing to an existing Plain Signer:

JSON

{
  "properties": {
    "CRYPTOTOKEN": "CryptoTokenP12",
    "AUTHTYPE": "NOAUTH",
    "IMPLEMENTATION_CLASS": "org.signserver.module.cmssigner.PlainSigner",
    "DEFAULTKEY": "signer00003",
    "TYPE": "PROCESSABLE",
    "DISABLEKEYUSAGECOUNTER": "true",
    "NAME": "PlainSigner"
  }
}

Change Worker Configuration

PATCH /workers/{id}

The PATCH/workers/{id} request only needs to contain the properties that you want to be added or changed. Remaining Worker properties are not affected by this request.

Use this endpoint to:

Change an existing property by providing a different value.
Add a property by providing it in the request body.

The body only needs to contain the properties that you want to be added or changed. Remaining Worker properties are not affected by this request.

Request

PATCH /signserver/rest/v1/workers/{id}

Request Body

Example body for changing the name of the Worker:

JSON

{
    "properties": {
        "NAME": "NewPlainSigner"
    }
}

cURL

Bash

curl --location --cert dss10_admin1.p12 --cert-type p12 --pass foo123 --request PATCH 'https://localhost:8443/signserver/rest/v1/workers/{id}' \
--header 'X-Keyfactor-Requested-With: X' \
--header 'Content-Type: application/json' \
--data-raw '{
    "properties": {
      "NAME": "NewPlainSigner"
    }
}'

Response

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

JSON

{
"responseMessage": "Worker properties successfully updated"
  }

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

PUT /workers/{id}

The PUT /workers/{id} request needs to contain all the properties of the Worker. This endpoint overwrites the full configuration of the provided Worker ID.

Use this endpoint to:

Change an existing property by providing a different value.
Remove a property by not providing it in the request.
Add a property by providing it in the request body.

If you do not want to change a property, you need to provide that property with the current value.

The body needs to contain all the properties of the Worker. The PUT /workers/{id} endpoint overwrites the full configuration of the provided Worker ID.

Request

PUT /signserver/rest/v1/workers/{id}

Request Body

Example request for changing the name of the Worker:

JSON

{
    "properties": {
        "CRYPTOTOKEN": "CryptoTokenP12",
        "AUTHTYPE": "NOAUTH",
        "IMPLEMENTATION_CLASS": "org.signserver.module.cmssigner.PlainSigner",
        "DEFAULTKEY": "signer00003",
        "TYPE": "PROCESSABLE",
        "DISABLEKEYUSAGECOUNTER": "true",
        "NAME": "NewPlainSigner"
    }
}

cURL

Bash

curl --location --cert dss10_admin1.p12 --cert-type p12 --pass foo123 --request PUT 'https://localhost:8443/signserver/rest/v1/workers/{id}' \
--header 'X-Keyfactor-Requested-With: X' \
--header 'Content-Type: application/json' \
--data-raw '{
    "properties": {
        "CRYPTOTOKEN": "CryptoTokenP12",
        "AUTHTYPE": "NOAUTH",
        "IMPLEMENTATION_CLASS": "org.signserver.module.cmssigner.PlainSigner",
        "DEFAULTKEY": "signer00003",
        "TYPE": "PROCESSABLE",
        "DISABLEKEYUSAGECOUNTER": "true",
        "NAME": "NewPlainSigner"
    }
}'

Response

If the request is successful, SignServer returns:

JSON

{
"responseMessage": "Worker properties successfully updated"
}

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

Remove Worker

DELETE /workers/{id}

The DELETE /workers/{id} endpoint removes the Worker with the provided ID. The endpoint will not take any body input from the request.

Request

DELETE /signserver/rest/v1/workers/{id}

cURL Example

Bash

curl --location --cert dss10_admin1.p12 --cert-type p12 --pass foo123 --request DELETE 'https://localhost:8443/signserver/rest/v1/workers/{id}' \
--header 'X-Keyfactor-Requested-With: X'

Response

If the request is successful, SignServer returns:

JSON

{
"responseMessage": "Worker removed successfully"
  }

If the request fails, SignServer returns an error message with the cause of the failure. For example, attempting to remove a Worker that does not exist returns status 404 Not Found with the error "No such worker: {id}".

Reload From Database

POST /workers/reload

The POST /workers/reload endpoint reloads the configuration from database. If the request metadata is left empty, it reloads all the Workers.

Request

POST /signserver/rest/v1/workers/reload

cURL Example

Bash

curl --location --cert dss10_admin1.p12 --cert-type p12 --pass foo123 --request POST 'https://localhost:8443/signserver/rest/v1/workers/reload' \
--header 'X-Keyfactor-Requested-With: X'

Response

If the request for reloading all Workers is successful, SignServer returns:

JSON

{
"responseMessage": "All workers successfully reloaded"
  }

If you only want to reload specific Workers, the desired Worker IDs can be provided in the body of the request.

Request Body

Example request for reloading specific Worker IDs:

JSON

{
  "workerIDs": [
    1, 2
  ]
}

cURL Example

Bash

curl --location --cert dss10_admin1.p12 --cert-type p12 --pass foo123 --request POST 'https://localhost:8443/signserver/rest/v1/workers/reload' \
--header 'X-Keyfactor-Requested-With: X' \
--header 'Content-Type: application/json' \
--data-raw '{
    "workerIDs": [
      1, 2
    ]
}'

Response

JSON

{
"responseMessage": "Workers successfully reloaded"
  }

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

Providing the Client Certificate

Admin endpoints require client certificate authentication over HTTPS. The examples on this page assume an authorized administrator certificate, such as the sample dss10_admin1.p12 keystore. How the certificate is presented depends on your HTTP client:

cURL

Provide the certificate file, type, and password with the request:

Bash

curl --cert dss10_admin1.p12 --cert-type p12 --pass foo123 \
  --header 'X-Keyfactor-Requested-With: REST' \
  --request GET 'https://localhost:8443/signserver/rest/v1/workers'

For more information on client certificates, see the curl - SSL CA Certificates documentation.

Postman

Add your client certificate under Postman’s Settings > Certificates > Add Certificate, associating it with the host and port your SignServer instance runs on. Postman then presents the certificate automatically for matching requests.

Python (Requests)

The requests library expects the certificate and key in PEM format. Convert the .p12 keystore first, then reference the files:

Python

import requests

response = requests.get(
    "https://localhost:8443/signserver/rest/v1/workers",
    headers={"X-Keyfactor-Requested-With": "REST"},
    cert=("admin1_cert.pem", "admin1_key.pem"),
)

Node.js

Pass the keystore to the HTTPS agent:

JavaScript

const https = require("https");
const fs = require("fs");

const agent = new https.Agent({
  pfx: fs.readFileSync("dss10_admin1.p12"),
  passphrase: "foo123",
});