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