Using Trusted Central Signing Service Document Seal API

Prerequisites

PhenixID Signing Service configured.

Cryptographic settings

All cryptographic settings are configured on the backend and cannot be set using the API.

API status codes

HTTP Status code Description
200
 OK
400
 Application error. Error message/detail/description is supplied in status message.
404
 The requested HTTP resource couldn’t be found. Note that this error is only used for HTTP and not for back end not found situations (like a query that didn’t return any results).
500
 Internal server errors. Used for errors not directly caused by the content of request - that wasn’t expected and/or couldn’t be handled be the application (network errors for example).

Authentication

- If PhenixID Signing Service Local Signing API is protected with client certificate authentication: Client certificate (p12) must be used for all requests.

- If PhenixID Signing Service Local Signing API is protected with basic authentication: Username and password authorization value must be added to all requests

APIs

Sync sign document

API to synchronously sign a document.

Currently supported document types:

  • PDF (application/pdf)

The media type of the supplied document must be specified in header Content-Type. Request with missing/invalid/unsupported Content-Type returns status 415 Unsupported Media Type.

The type of the returned document is specified in header Accept. If media type specified can’t be handled, status 406 Not Acceptable is returned. If no media type is specified the default type for the supplied input is used.

URL: <baseUrl>/pipes/seal

Method: PUT

Auth: Client certificate (recommended), Basic authentication or No authentication (only for test purposes)

Parameters: filename [OPTIONAL]

Example request

PUT /pipes/seal HTTP/1.1
Host: example.org
Content-Type: application/pdf
Content-Length: <length>
Accept: application/pdf
.
<Body - the PDF document to sign>
.

Example response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: <length>
.
<Body - the signed PDF document>
.

 

Verify document

 

API to verify the signature of a document.

URL: <baseUrl>/pipes/verifyseal

Method: PUT

Auth: Client certificate (recommended), Basic authentication or No authentication (only for test purposes)

Example request

PUT /pipes/verifyseal HTTP/1.1
Host: example.org
Content-Type: application/pdf
Content-Length: <length>

.
<Body - the PDF document to verify>
.

 

Response

The body response will contain a json structure with these properties.

 

Name Possible values Comment
success true
false		 Result of the verification
error_code
Error code when success=false
error_message
Error message when success=false
error_detail_message
Detailed error message when success=false

Example response - verification successful

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>
.
{
    "success": true,
    "items": [],
    "error_message": "",
    "error_detail_message": ""
}

Example response - verification failed

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: <length>
.
{
    "success": false,
    "items": [
        {
            "id": "temp",
            "properties": {
            }
        }
    ],
    "error_code": 1101,
    "error_message": "PDF signature validation failed.",
    "error_detail_message": ""
}