...
The PKIsigning API consists of four operations:
StartSignFlow
RetrieveDocument
RemoveDocument
GetWorkgroupWithClearanceLevel
StartSignFlow
| Urgent |
|---|
The API documentation is showing several fields in the request that are only present for backwards compatibility. /document These properties have been replaced by their successors in the /documents array and therefore allow for sending multiple files. |
...
It is not possible to set a higher clearance level than specified in the list retrieved from GetWorkgroupWithClearanceLevel.
| Urgent |
|---|
As PKIsigning charges credits for requests when fulfilled, credits are being reserved at the moment of submitting the request to prevent running out of credits while actually fulfilling it. If the amount of credits is insufficient to fulfill the request, a HTTP status 402 (Payment required) is returned. During development phase, please use either short deadlines or delete requests from the platform and clean up the recyblebin to prevent running out of credits. If a request is not signed nor downloaded by a recipient, any credits that were reserved for that request will become available again when the request is removed. |
Callback
It is possible to subscribe to status events on the PKIsigning platform. To subscribe, specify a callbackUrl in the StartSignFlow call. For each change in status, this url will be called using HTTP POST with a body like the following example:
...
The authentication key is only available for use in the V2 API.
To validate the origin of the callback, the callback is signed using three values in the HTTP header.
x-pkisigning-timestamp: the value of this header prevents against replay attacks and should be checked by the receiver. Normally there should not be more than a few seconds difference in time when the time of receiving system is synced through NTP.
x-pkisigning-publickey: This value contains a PKCS7 encoded certificate that was used to sign the callback request. Validate if the certificate is provided by a valid trusted service provider, is not revoked, is within its validity period and most important if the certificate contains a PKIsigning (sub)domain (we use the top level domains PKIsigning.io and PKIsigning.nl).
x-pkisigning-signature: this value contains the RSASHA256 signature of the contents combined with the timestamp. To check the signature follow the following procedure:
obtain the raw bytes of the payload (UTF-8 encoding)
obtain the bytes of the timestamp (UTF-8 encoding)
concatenate both byte sequences into one byte sequence
verify the signature against the certificate
RetrieveDocument
The RetrieveDocument call can be used to obtain a zip-file containing all documents of a single request. When a callback url was specified during the StartSignFlow call, this url is called upon status updates, after which RetrieveDocument may be called.
...