This section provides a reference for APIs that should be implemented by this Building Block.
A Set of microservices is defined to receive requests from other GovStack-compatible Building Blocks and third-party Services with relevant inputs and return processed results from key digital functionalities of this Building Block. This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks or third-party services. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
eSignature Building Block must expose its microservices through RESTful API interfaces as defined by OpenAPI v3+ standards. A summary of the APIS exposed by this Building Block is summarized in the table below.
The update API can be used to revoke the certificate. All revoked certificates will be available over OCSP.
eSignature BB will call this callback URL on external service once signing is completed
API version
signatureId that can be used to retreive the response as hex string of hash
hex string value of hash to mitigate replay attacks
hex string value of hash used to maintain state between the request and the callback
Returns html for continuing user's flow
Provide interactive html for pseodonym entry form that will get the signature via sign/pseudonym and will call callbackUrl
API version
Pre format the signature in a give format so that it can be more inserted by the formatting library XAdES|CAdES|ASIC|JWS|PAdES
hash as byte array encoded in base64
hash type used SHA2-256|SHA2-384|SHA2-512|SHA3-256|SHA3-384|SHA3-512|BLAKE2B
Data to be displayed on users SCD (for ex transactionId)
Timestamp in ISO 8601
hex string value of hash to mitigate replay attacks
hex string value of hash used to maintain state between the request and the callback
Callback url to be sent on signing response. Callback URL will have query parameters from SignatureResponse statusCode(base64urlencoded), statusMessage(base64urlencoded), signature (base64urlencoded), certificate (base64urlencoded), signatureTimestamp (base64urlencoded), responseTimestamp (urlencoded), pseudonymToken (jwt)
Returns html for entering pseudonym
In order not to get the pseodonym token internally
API version
Unique pseudonym
Pseodonym token generated successfully
jwt pseudonym authorization
Get list of all user certificates
API version
Add filter condition ALL|ACTIVATED|EXPIRED|REVOKED|SUSPENDED
JWT Authentication token received from ID BB
List certificates response
Id that is later used to send signature requests to a person
X.509 certificate in PEM format
Certificate status ACTIVE|ERROR|EXPIRED|SUSPENDED|REVOKED
Certificate active
In order not to get the pseodonym token internally
API version
get signature response for signatureId
Signature response
signature in base64 format
X.509 certificate in PEM format
Timestamp in ISO 8601
rfc3161 asn.1 in base64
Signature creation response OK|ERROR
Signature creation message
Update certificate status
API version
certificateId that indicates the certificate to be updated
JWT Authentication token received from ID BB
Timestamp in ISO 8601
Certificate status to be updated ACTIVATE|SUSPEND|REVOKE, Allowed transitions ACTIVE->SUSPENDED, ACTIVE->REVOKED, SUSPENDED->ACTIVE, SUSPENDED->REVOKED
Certificate update message
Update certificate response
Timestamp in ISO 8601
Certificate status ERROR|ACTIVATED|SUSPENDED|REVOKED|EXPIRED
Certificate supended because of user action on 02.02.2023
Way for users and auditors to review the signature requests made
API version
Timestamp in ISO 8601
Timestamp in ISO 8601
JWT Authentication token received from ID BB
Audit response
signature type ONETIME|SCD
signature in base64 format
X.509 certificate in PEM format
Timestamp in ISO 8601
rfc3161 asn.1 in base64
Signature creation response OK|ERROR
Signature creation message
Use user's SCD (Signature Creation Device) to create an eSignature
API version
JWT pseudonym token
Pre format the signature in a give format so that it can be inserted by the formatting library XAdES|CAdES|ASIC|JWS|PAdES
hash as byte array encoded in base64
hash type used SHA2-256|SHA2-384|SHA2-512|SHA3-256|SHA3-384|SHA3-512|BLAKE2B
Data to be displayed on users SCD (for ex transactionId)
hex string value of hash to mitigate replay attacks
hex string value of hash used to maintain state between the request and the callback
Timestamp in ISO 8601
Signature response
signatureId that can be used to retreive the response as hex string of hash
hex string value of hash to mitigate replay attacks
hex string value of hash used to maintain state between the request and the callback
Use one time Certificate and keys created on the fly to make an eSignature
API version
JWT Authentication token received from ID BB
JWT Authentication token received from Payment BB
Pre format the signature in a given format so that it can be inserted by the formatting library XAdES|CAdES|ASIC|JWS|PAdES
hash as byte array encoded in base64
hash type used SHA2-256|SHA2-384|SHA2-512|SHA3-256|SHA3-384|SHA3-512|BLAKE2B
Data to be displayed on users SCD (for ex transactionId)
Timestamp in ISO 8601
Signature response
signature in base64 format
X.509 certificate in PEM format
Timestamp in ISO 8601
rfc3161 asn.1 in base64
Signature creation response OK|ERROR
Signature creation message
Create certificate on user's SCD (Signature Creation Device)
API version
JWT Authentication token received from ID BB
JWT Authentication token received from Payment BB
Certificate Signing Request, in base64
Remote SCD type REMOTE_SCD_APP_APPLE|REMOTE_SCD_APP_ANDROID|REMOTE_SCD_APP_SE_APPLE|REMOTE_SCD_APP_SE_ANDROID|REMOTE_SCD_SIM|REMOTE_SCD_ESIM
Device token (Android/Apple) for REMOTE_SCD_APP* and REMOTE_SCD_APP_SE*, for other TBD
Key index to be used on SCD
Optional pseodonym chosen by user
Timestamp in ISO 8601
Certificate creation response
Id that is later used to send signature requests to a person
Unique pseudonym that can be used to lookup certificateId by external service. If not specified, will be created automatically.
X.509 certificate in PEM format
Timestamp in ISO 8601
Certificate creation response OK|ERROR
Certificate creation message