REST API Interface

The SignServer REST Interface provides a RESTful Web Service for integrating with SignServer programmatically. It supports signing operations and, in future versions, may be extended to cover additional interfaces and API calls.

The REST API reference documentation is divided based on administrative or signing purposes:

• Admin REST Endpoints

• Client REST Endpoints

Before You Begin

Before making your first request, confirm the following)

• Base URL. All endpoints are relative to your SignServer installation. See Base URLs for the specific base path to use depending on whether you are calling an admin, signing, or managed client endpoint.

• Worker ID or name. Every request targets a specific Worker. You can identify a Worker by its numeric ID or its name. If the value you pass for {idOrName} is numeric, SignServer treats it as a Worker ID. Any non-numeric value is treated as a Worker name.

• TLS and authentication. Production deployments typically require client certificate authentication over HTTPS. Confirm your server authentication requirements before integrating.

About Requests to the REST API

Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, query parameters, or body parameters.

The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses in a tool-agnostic format that can be used with any HTTP client, such as cURL, Postman, Python, or JavaScript.

HTTP Method

The HTTP method of an endpoint defines the type of action it performs on a given resource. The REST API reference documentation provides the HTTP method for every endpoint.

Signing requests use the following HTTP methods:

• GET : Used for retrieving resources.

• POST : Used for creating resources.

• PAtch : Used for updating properties of resources.

• PUT : Used for replacing resources or collections of resources.

• Delete : Used for deleting resources.

The following table provides signing examples of the HTTP POST method:

For file upload requests, the response Content-Type varies depending on the Signer the request is sent to.

Base URLs

The REST Interface uses different base URLs depending on the category of endpoint you are calling:

Path

Each endpoint has a path. The REST API reference documentation gives the path for every endpoint. For example, the path for the “Sign Data” endpoint is /workers/{idOrName}/process.

The curly brackets {} in a path denote path parameters that you need to specify. Path parameters modify the endpoint path and are required in your request. For example, the path parameter for the “Sign Data” endpoint is {idOrName}. To use this path in your API request, replace {idOrName} with the name or ID of the Worker you want to use.

Custom Request Header

All requests must include the header X-Keyfactor-Requested-With with any non-empty string value (for example, REST). This header protects admin endpoints from being maliciously invoked from administrator machines by clickjacking or CSRF methods. Requests that omit it will be rejected.

Quick Start

The following example signs a string using a Plain Signer. Replace PlainSigner with your Worker name or ID, and update the base URL to match your environment.

Request

POST /signserver/rest/v1/workers/PlainSigner/process

Request Body

{
  "data": "Hello, SignServer!"
}

Response

A successful response returns a JSON object containing the signature in the data field:

{
  "archiveId": "12aab5dba45d5fbe538a1d210287ae4912df677b",
  "data": "<base64-encoded signature>",
  "metaData": {},
  "requestId": "1277380144",
  "signerCertificate": "<base64-encoded DER certificate>"
}

See Response Fields for a description of each field.

API Overview

OpenAPI Specification

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.

The interface is documented in an OpenAPI document in YAML or JSON format. These documents may be produced and served statically or generated dynamically from an application:

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

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.

Resource

The SignServer REST API provides the following resource for all signing operations:

/rest/v1/workers

Response Fields

All signing responses return a JSON object with the following fields:

Error Responses

If a request fails, SignServer returns an error object. For example:

{
  "errorMessage": "No such worker: UnknownSigner",
  "errorCode": 404
}

Common causes of errors include:

Examples by Use Case

For examples across common use cases, see:

• Add New Worker

• Reload From Database

• Sign Data

• Client-side Hashing