REST Interface

The following covers information on the SignServer REST Interface.

API Overview

The SignServer REST Interface supports integration with SignServer over a RESTful Web Service. This is a more modern and RESTful alternative to the Client WS Interface and the Client HTTP Interface.

In future versions, the interface may be extended to support additional API calls from other interfaces and/or add new ones.

Getting Started

The SignServer REST interface is described using the OpenAPI Specification (OAS). The OpenAPI Specification is a community-driven specification for describing REST APIs.

OpenAPI documents describe API services and are represented in YAML or JSON formats. These documents may be produced and served statically or generated dynamically from an application.

OpenAPI Document

The interface is documented in an OpenAPI document in YAML or JSON format:

Document	JSON	YAML
SignServer REST Interface 1.3.1	openapi.json	openapi.yaml

These files can be downloaded and opened in an editor of choice.

Alternatively, you can generate the OpenAPI document from a server running SignServer, assuming that it is enabled and supported by the application server. For instructions, see Generate the OpenAPI Document.

Integrating with the REST API

Resources

The SignServer REST API provides the following resource:

CODE

/rest/v1/workers

Methods

Each request requires a specified HTTP method.

A numeric value for {idOrName} is treated by SignServer as a WorkerID. If the {idOrName} value is not numeric, SignServer takes it as a worker name.

Method	URL	Accept	Request Content-Type	Request Parameters	Response Content-Type
POST	/rest/v1/workers/{idOrName}/process	application/json	application/json	data, metadata, encoding	application/json
POST	/rest/v1/workers/{idOrName}/process	application/octet-stream	multipart/form-data	file (field name not important) REQUEST_METADATA.x REQUEST_METADATA x=y	For file uploads, the Content-Type varies depending on the signer the request is sent to.
POST	/rest/v1/workers/{idOrName}/process	application/json	multipart/form-data	data, metadata, encoding	application/json

Custom Header Requirements

The admin operations of the SignServer REST API require a custom header called "X-Keyfactor-Requested-With" to accept the request. This protects SignServer REST endpoints from being maliciously invoked from administrator machines by clickjacking or CSRF methods.

Using the SignServer REST API

The REST API can be used with various tools. For detailed examples, see: