REST endpoints using Postman

The following covers how to use Postman 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.

Configure Postman

The examples use Postman to send requests to the SignServer REST endpoints. For Postman to be able to send requests that will not be rejected by SignServer, you need to configure your Postman instance.

First, add your certificate to the host and port you are running your SignServer instance on. This is done under Settings>Certificates>Add Certificates.

In these examples, the certificate has been added to localhost:8443 and localhost:8080.

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

As mentioned in Admin REST Interface, SignServer has a custom header that is required. This header can be configured by setting X-Keyfactor-Requested-With under Headers. This needs to be done for each new request.

Use REST Endpoints to Configure Workers in SignServer

Add a 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}

Submit a list of properties to add a new Worker.

An example body for sending a request to create a Plain Signer:

JSON

{
   "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 returns status 201 Created. If the request fails, SignServer returns an error message with the cause of the failure.

For example, a conflict for the chosen Worker ID can return status 409 Conflict, with the error:

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

Or a conflict for the chosen Worker name can return status 409 Conflict, with the error:

 "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 endpoint GET /workers only returns the ID and name of the existing Workers on the SignServer instance. It will not look at the body even if one is provided.

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 more detailed configuration for a specified Worker. This endpoint does not use the body even if one is provided.

Example response for ID provided 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}

Use this endpoint to:

Change the 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.

Example body for changing the name of the Worker:

JSON

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

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

"responseMessage": "Worker properties successfully updated".

If the request fails, SignServer returns an error message with the cause of the failure.
For example, if you attempt to make changes to a Worker ID that does not exist, the failure returns status 404 Not Found with response body:

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

Endpoint: PUT /workers/{id}

Use this endpoint to:

Change the 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.

All properties that you do not want to change need to be provided 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.

Example body 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"
    }
}

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

"responseMessage": "Worker properties successfully replaced".

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

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.

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

"responseMessage": "Worker removed successfully"

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

Reload from Database

Endpoint: POST /workers/reload

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

If the request to reload all Workers is successful, SignServer will return status 200 OK with the following response body:

"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 body for reloading defined Worker IDs:

JSON

{
  "workerIDs": [
    1, 2
  ]
}

If the request is successful, SignServer will return status 200 OK with the following response body "responseMessage": "Workers successfully reloaded".

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, status 404 Not Found with response body "error": "No such worker: {id}", for trying to reload a Worker that does not exist.