REST endpoints using cURL | Keyfactor Docs

The following covers how to use cURL to send requests to the SignServer REST API, including required configuration, example requests, and typical responses.

For using REST endpoints for signing and retrieving keys and certificates, see Client REST Interface.

Using cURL

The examples provided use cURL to send requests to the SignServer REST endpoints.

Base HTTPS URL used for all admin requests:

https://localhost:8443/signserver/rest/v1

Base HTTP URL used for signing requests:

http://localhost:8080/signserver/rest/v1

Base HTTP URL used for Enterprise Client endpoints:

http://localhost:8080/signserver/rest-managed/v1

Configure Workers Using REST Endpoints in SignServer

Add New Worker

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

Endpoint: POST /workers or /workers/{id}

Example request to create a Plain Signer:

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"
    }
}'

If the request is successful, SignServer does not return any errors. If the request fails, SignServer returns an error message with the cause of the failure.

Example error message of a conflict with the chosen Worker name:

{"error":"Worker already exists: PlainSigner"}

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.

Endpoint: 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 body even if one is provided.

Example request:

Bash

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

Example response to an empty body:

JSON

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

Endpoint: GET /workers/{id}

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

Example request:

Bash

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

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

Endpoint: 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.

Example body for changing the name of the Worker:

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"
    }
}'

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.

Example error message for trying to make changes to a Worker ID that does not exists:

JSON

{
  "error": "No such worker: 3"
}

Endpoint: 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.

Example request for changing the name of the Worker:

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"
    }
}'

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.

Example error message for trying to make changes to a Worker ID that does not exists:

JSON

{
  "error": "No such worker: 3"
}

Remove Worker

Endpoint: 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.

Example of removing a Worker:

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'

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.

Example error message for trying to delete a Worker ID that does not exists:

JSON

{
  "error": "No such worker: {id}"
}

Reload From Database

Endpoint: 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.

Example of request reloading all Workers:

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'

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 wanted Worker IDs can be provided in the body of the request.

Example request for reloading defined Worker IDs:

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
    ]
}'

If the request is successful, SignServer returns:

JSON

{
  "responseMessage": "Workers successfully reloaded"
}

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

Example error message for trying to reload a Worker ID that does not exists:

JSON

{
  "error": "No such worker: {id}"
}