LogoLogo
Give FeedbackGovStack Home
23Q4
23Q4
  • E-Signature
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
  • 9 Internal Workflows
  • 10 Other Resources
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF

8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

Last updated 1 year ago

Was this helpful?

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 . A summary of the APIS exposed by this Building Block is summarized in the table below.

8.1 eSignature with one-time certificate

8.2 eSignature with user's eSignature creation device (SCD)

8.2.1 Certificate creation

8.2.2 List certificates

8.2.3 Update certificate

8.2.4 eSignature with user's device

8.2.5 Webservice to enter user pseudonym

8.2.6 User pseudonym API

8.2.7 Get signature response

8.2.8 Callback service API

8.3 Audit log

The update API can be used to revoke the certificate. All revoked certificates will be available over .

OCSP
OpenAPI v3+ standards

Get list of all user certificates

get

Get list of all user certificates

Path parameters
versionstringRequired

API version

Example: v1
Query parameters
filterstring · enumOptional

Add filter condition ALL|ACTIVATED|EXPIRED|REVOKED|SUSPENDED

Example: ALLPossible values:
Header parameters
X-GovStack-AuthenticationTokenstringRequired

JWT Authentication token received from ID BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Responses
200
List certificates response
application/json
400
Bad request
404
Not found
422
Mandatory field not present
429
Too many requests
get
GET /{version}/cert/list HTTP/1.1
Host: localhost:9090
X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Accept: */*
[
  {
    "certificateId": "09440694c5c1798a23aad320abcd04b83f02f5ea12b8865df073d0e77ad5ae27",
    "certificate": "-----BEGIN CERTIFICATE-----\r\nMIIDfDCCAmSgAwIBAgIQaSg0J93/hMMyFZ/DNEDM3DANBgkqhkiG9w0BAQsFADAp\r\nMScwJQYDVQQDDB5CLkVzdCBTb2x1dGlvbnMgU2lnbmluZyBQb3J0YWwwHhcNMjMw\r\nNDE0MTAzOTA5WhcNMjUwNzE3MTAzOTA5WjATMREwDwYDVQQDDAhKb2huIERvZTCC\r\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANU2fYwu2tz/D4GpTZZhPn4g\r\nFTH4TSbez1Ux9eMsmklYrmqdr3bBzJ4k8I1wkOBioxrXnH/s4zq7I1dJCbAsAzpd\r\niK8IBHo5XxwX2Num+HxRdU+nTOtfa4MZTGnvf4ZzLYBEK1lIsXQxAbMkPu4cBH8t\r\n9ir72GGU2qM/iMOv25eA75+cmNFj+02DohgpxXhErnZB/9mY+8oLvIFM5traf92U\r\nF4OPsepQYpJUM4u2prxbdcwVCmZ70FielcykaG7u84PRKbmAA50x2UQgsksThmxA\r\nPJlIvEoCS4BAAoLlY+ti0IFhThqYjG+FcRR5R48wa+oAJBquDG1eko6dTzp3BdEC\r\nAwEAAaOBtTCBsjAJBgNVHRMEAjAAMB0GA1UdDgQWBBR68RAciltftWZW4pAxqMQ0\r\nhigSEzBkBgNVHSMEXTBbgBRYpaezWi0heg09El0UypLU81uA4KEtpCswKTEnMCUG\r\nA1UEAwweQi5Fc3QgU29sdXRpb25zIFNpZ25pbmcgUG9ydGFsghQZ+B3m7iBv8Daf\r\nWiIkRB5NbVbQsTATBgNVHSUEDDAKBggrBgEFBQcDAjALBgNVHQ8EBAMCB4AwDQYJ\r\nKoZIhvcNAQELBQADggEBAI+5OAffnf3sn/jN58idSLUC09vWc6KPEzfZ2QLhDftq\r\nAfwSquItYFFuuQNh/x93HSprglDwL3U6sqRq0owMSSXXcLctVQr/MTEXyiRmQjUT\r\nHykwS/ovSw93E6VRnrF0qnaf6qOOAi0FfLxCV/1p3aEQBt7f/krZaW4Y33XrKi5F\r\nNnMhqQLtgZy9xXR0dNQ0ZKorEIptUrcujT8aRlEN4oqE7oo4j41TsksBQgEFfIeg\r\nljS6baoEko6n5ozyFzfeDWzd0yTzviXmUZGzOt1ZLFbd5In5+LX4Z0QwzhUA+uyt\r\nCu17qrRiPt2JzALHjbkdV3OB5sbOSZDHl3aUuqll6Dg=\r\n-----END CERTIFICATE-----",
    "status": {
      "code": "ACTIVE",
      "message": "Certificate active"
    }
  },
  {
    "certificateId": "a92dba58903a6387aedee6f178d84de674e6a9b7d779a8e6add3db5f752ce5ab",
    "certificate": "-----BEGIN CERTIFICATE-----\r\nMIIDfDCCAmSgAwIBAgIQaSg0J93/hMMyFZ/DNEDM3DANBgkqhkiG9w0BAQsFADAp\r\nMScwJQYDVQQDDB5CLkVzdCBTb2x1dGlvbnMgU2lnbmluZyBQb3J0YWwwHhcNMjMw\r\nNDE0MTAzOTA5WhcNMjUwNzE3MTAzOTA5WjATMREwDwYDVQQDDAhKb2huIERvZTCC\r\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANU2fYwu2tz/D4GpTZZhPn4g\r\nFTH4TSbez1Ux9eMsmklYrmqdr3bBzJ4k8I1wkOBioxrXnH/s4zq7I1dJCbAsAzpd\r\niK8IBHo5XxwX2Num+HxRdU+nTOtfa4MZTGnvf4ZzLYBEK1lIsXQxAbMkPu4cBH8t\r\n9ir72GGU2qM/iMOv25eA75+cmNFj+02DohgpxXhErnZB/9mY+8oLvIFM5traf92U\r\nF4OPsepQYpJUM4u2prxbdcwVCmZ70FielcykaG7u84PRKbmAA50x2UQgsksThmxA\r\nPJlIvEoCS4BAAoLlY+ti0IFhThqYjG+FcRR5R48wa+oAJBquDG1eko6dTzp3BdEC\r\nAwEAAaOBtTCBsjAJBgNVHRMEAjAAMB0GA1UdDgQWBBR68RAciltftWZW4pAxqMQ0\r\nhigSEzBkBgNVHSMEXTBbgBRYpaezWi0heg09El0UypLU81uA4KEtpCswKTEnMCUG\r\nA1UEAwweQi5Fc3QgU29sdXRpb25zIFNpZ25pbmcgUG9ydGFsghQZ+B3m7iBv8Daf\r\nWiIkRB5NbVbQsTATBgNVHSUEDDAKBggrBgEFBQcDAjALBgNVHQ8EBAMCB4AwDQYJ\r\nKoZIhvcNAQELBQADggEBAI+5OAffnf3sn/jN58idSLUC09vWc6KPEzfZ2QLhDftq\r\nAfwSquItYFFuuQNh/x93HSprglDwL3U6sqRq0owMSSXXcLctVQr/MTEXyiRmQjUT\r\nHykwS/ovSw93E6VRnrF0qnaf6qOOAi0FfLxCV/1p3aEQBt7f/krZaW4Y33XrKi5F\r\nNnMhqQLtgZy9xXR0dNQ0ZKorEIptUrcujT8aRlEN4oqE7oo4j41TsksBQgEFfIeg\r\nljS6baoEko6n5ozyFzfeDWzd0yTzviXmUZGzOt1ZLFbd5In5+LX4Z0QwzhUA+uyt\r\nCu17qrRiPt2JzALHjbkdV3OB5sbOSZDHl3aUuqll6Dg=\r\n-----END CERTIFICATE-----",
    "status": {
      "code": "REVOKED",
      "message": "Certificate was revoked on 05.01.2023 because device was lost"
    }
  }
]

Create a SCD eSignature with interactive pseodonym entry

get

Provide interactive html for pseodonym entry form that will get the signature via sign/pseudonym and will call callbackUrl

Path parameters
versionstringRequired

API version

Example: v1
Query parameters
formatstring · enumOptional

Pre format the signature in a give format so that it can be more inserted by the formatting library XAdES|CAdES|ASIC|JWS|PAdES

Example: PAdESPossible values:
hashstring · base64urlencodedOptional

hash as byte array encoded in base64

Example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
hashTypestring · enumOptional

hash type used SHA2-256|SHA2-384|SHA2-512|SHA3-256|SHA3-384|SHA3-512|BLAKE2B

Example: SHA2-256Possible values:
dataToBeDisplayedstring · base64urlencodedOptional

Data to be displayed on users SCD (for ex transactionId)

Example: UGxlYXNlIHNpZ24gdGhlIGNvbnNlbnQgZm9ybSBhcyByZXF1ZXN0ZWQgKHRyYW5zYWN0aW9uSWQ6MTIzNCk
requestTimestampstring · urlencodedOptional

Timestamp in ISO 8601

Example: 2023-03-20T09%3A12%3A28Z
noncestring · urlencodedOptional

hex string value of hash to mitigate replay attacks

Example: d2dff00401c92ca6879ef5f0938ce31580898266d59832d8531e8d04fc3898a6
statestring · urlencodedOptional

hex string value of hash used to maintain state between the request and the callback

Example: 2569cb4125cb7303f0f16782e7e2814b2269888c734af4c90639653e4f92d3a5
callbackUrlstring · urlencodedOptional

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)

Example: https%3A%2F%2Fmysite
Responses
200
Returns html for entering pseudonym
text/html
Responsestring
400
Bad request
404
Not found
422
Mandatory field not present
429
Too many requests
get
GET /{version}/sign/interactivePseudonym HTTP/1.1
Host: localhost:9090
Accept: */*
text

Get pseodunym token

get

In order not to get the pseodonym token internally

Path parameters
versionstringRequired

API version

Example: v1
pseudonymstringRequired

Unique pseudonym

Example: johndoe5766
Responses
200
Pseodonym token generated successfully
application/json
400
Bad request
404
Not found
422
Mandatory field not present
429
Too many requests
get
GET /{version}/token/pseodonym/{pseudonym} HTTP/1.1
Host: localhost:9090
Accept: */*
{
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA"
}

Get signature response

get

In order not to get the pseodonym token internally

Path parameters
versionstringRequired

API version

Example: v1
signatureIdstringRequired

get signature response for signatureId

Example: 7607fa7f45b2558201baf05215521a7df63078774f0b0d1ad15ccfcb0aad9484
Responses
200
Signature response
application/json
400
Bad request
404
Not found
422
Mandatory field not present
429
Too many requests
get
GET /{version}/sign/response/{signatureId} HTTP/1.1
Host: localhost:9090
Accept: */*
{
  "signature": "53F4yGNsOXymuGL9JjF3Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==",
  "certificate": "-----BEGIN CERTIFICATE-----\r\nMIIDfDCCAmSgAwIBAgIQaSg0J93/hMMyFZ/DNEDM3DANBgkqhkiG9w0BAQsFADAp\r\nMScwJQYDVQQDDB5CLkVzdCBTb2x1dGlvbnMgU2lnbmluZyBQb3J0YWwwHhcNMjMw\r\nNDE0MTAzOTA5WhcNMjUwNzE3MTAzOTA5WjATMREwDwYDVQQDDAhKb2huIERvZTCC\r\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANU2fYwu2tz/D4GpTZZhPn4g\r\nFTH4TSbez1Ux9eMsmklYrmqdr3bBzJ4k8I1wkOBioxrXnH/s4zq7I1dJCbAsAzpd\r\niK8IBHo5XxwX2Num+HxRdU+nTOtfa4MZTGnvf4ZzLYBEK1lIsXQxAbMkPu4cBH8t\r\n9ir72GGU2qM/iMOv25eA75+cmNFj+02DohgpxXhErnZB/9mY+8oLvIFM5traf92U\r\nF4OPsepQYpJUM4u2prxbdcwVCmZ70FielcykaG7u84PRKbmAA50x2UQgsksThmxA\r\nPJlIvEoCS4BAAoLlY+ti0IFhThqYjG+FcRR5R48wa+oAJBquDG1eko6dTzp3BdEC\r\nAwEAAaOBtTCBsjAJBgNVHRMEAjAAMB0GA1UdDgQWBBR68RAciltftWZW4pAxqMQ0\r\nhigSEzBkBgNVHSMEXTBbgBRYpaezWi0heg09El0UypLU81uA4KEtpCswKTEnMCUG\r\nA1UEAwweQi5Fc3QgU29sdXRpb25zIFNpZ25pbmcgUG9ydGFsghQZ+B3m7iBv8Daf\r\nWiIkRB5NbVbQsTATBgNVHSUEDDAKBggrBgEFBQcDAjALBgNVHQ8EBAMCB4AwDQYJ\r\nKoZIhvcNAQELBQADggEBAI+5OAffnf3sn/jN58idSLUC09vWc6KPEzfZ2QLhDftq\r\nAfwSquItYFFuuQNh/x93HSprglDwL3U6sqRq0owMSSXXcLctVQr/MTEXyiRmQjUT\r\nHykwS/ovSw93E6VRnrF0qnaf6qOOAi0FfLxCV/1p3aEQBt7f/krZaW4Y33XrKi5F\r\nNnMhqQLtgZy9xXR0dNQ0ZKorEIptUrcujT8aRlEN4oqE7oo4j41TsksBQgEFfIeg\r\nljS6baoEko6n5ozyFzfeDWzd0yTzviXmUZGzOt1ZLFbd5In5+LX4Z0QwzhUA+uyt\r\nCu17qrRiPt2JzALHjbkdV3OB5sbOSZDHl3aUuqll6Dg=\r\n-----END CERTIFICATE-----",
  "signatureTimestamp": "r/PzWEEgXyubXH/GCG6fLADU9Rz4e3b0KdZuNwfX/xk=",
  "responseTimestamp": "2023-03-20T09:12:38Z",
  "status": {
    "code": "OK",
    "message": "Signature generated successfully"
  }
}

Implement eSignature callback API

get

eSignature BB will call this callback URL on external service once signing is completed

Path parameters
versionstringRequired

API version

Example: v1
Query parameters
signatureIdstringRequired

signatureId that can be used to retreive the response as hex string of hash

Example: 7607fa7f45b2558201baf05215521a7df63078774f0b0d1ad15ccfcb0aad9484
noncestring · urlencodedRequired

hex string value of hash to mitigate replay attacks

Example: d2dff00401c92ca6879ef5f0938ce31580898266d59832d8531e8d04fc3898a6
statestring · urlencodedRequired

hex string value of hash used to maintain state between the request and the callback

Example: 2569cb4125cb7303f0f16782e7e2814b2269888c734af4c90639653e4f92d3a5
Responses
200
Returns html for continuing user's flow
text/html
Responsestring
get
GET /{version}/esignature/callback HTTP/1.1
Host: localhost:9090
Accept: */*
200

Returns html for continuing user's flow

text

Audit transactions

get

Way for users and auditors to review the signature requests made

Path parameters
versionstringRequired

API version

Example: v1
Query parameters
startstring · urlencodedOptional

Timestamp in ISO 8601

Example: 2023-03-20T09%3A12%3A28Z
endstring · urlencodedOptional

Timestamp in ISO 8601

Example: 2023-03-20T09%3A12%3A28Z
Header parameters
X-GovStack-AuthenticationTokenstringRequired

JWT Authentication token received from ID BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Responses
200
Audit response
application/json
400
Bad request
401
ID BB Authentication required
404
Not found
422
Mandatory field not present
429
Too many requests
get
GET /{version}/audit/log HTTP/1.1
Host: localhost:9090
X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Accept: */*
[
  {
    "signatureType": "ONETIME",
    "signature": "53F4yGNsOXymuGL9JjF3Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==",
    "certificate": "-----BEGIN CERTIFICATE-----\r\nMIIDfDCCAmSgAwIBAgIQaSg0J93/hMMyFZ/DNEDM3DANBgkqhkiG9w0BAQsFADAp\r\nMScwJQYDVQQDDB5CLkVzdCBTb2x1dGlvbnMgU2lnbmluZyBQb3J0YWwwHhcNMjMw\r\nNDE0MTAzOTA5WhcNMjUwNzE3MTAzOTA5WjATMREwDwYDVQQDDAhKb2huIERvZTCC\r\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANU2fYwu2tz/D4GpTZZhPn4g\r\nFTH4TSbez1Ux9eMsmklYrmqdr3bBzJ4k8I1wkOBioxrXnH/s4zq7I1dJCbAsAzpd\r\niK8IBHo5XxwX2Num+HxRdU+nTOtfa4MZTGnvf4ZzLYBEK1lIsXQxAbMkPu4cBH8t\r\n9ir72GGU2qM/iMOv25eA75+cmNFj+02DohgpxXhErnZB/9mY+8oLvIFM5traf92U\r\nF4OPsepQYpJUM4u2prxbdcwVCmZ70FielcykaG7u84PRKbmAA50x2UQgsksThmxA\r\nPJlIvEoCS4BAAoLlY+ti0IFhThqYjG+FcRR5R48wa+oAJBquDG1eko6dTzp3BdEC\r\nAwEAAaOBtTCBsjAJBgNVHRMEAjAAMB0GA1UdDgQWBBR68RAciltftWZW4pAxqMQ0\r\nhigSEzBkBgNVHSMEXTBbgBRYpaezWi0heg09El0UypLU81uA4KEtpCswKTEnMCUG\r\nA1UEAwweQi5Fc3QgU29sdXRpb25zIFNpZ25pbmcgUG9ydGFsghQZ+B3m7iBv8Daf\r\nWiIkRB5NbVbQsTATBgNVHSUEDDAKBggrBgEFBQcDAjALBgNVHQ8EBAMCB4AwDQYJ\r\nKoZIhvcNAQELBQADggEBAI+5OAffnf3sn/jN58idSLUC09vWc6KPEzfZ2QLhDftq\r\nAfwSquItYFFuuQNh/x93HSprglDwL3U6sqRq0owMSSXXcLctVQr/MTEXyiRmQjUT\r\nHykwS/ovSw93E6VRnrF0qnaf6qOOAi0FfLxCV/1p3aEQBt7f/krZaW4Y33XrKi5F\r\nNnMhqQLtgZy9xXR0dNQ0ZKorEIptUrcujT8aRlEN4oqE7oo4j41TsksBQgEFfIeg\r\nljS6baoEko6n5ozyFzfeDWzd0yTzviXmUZGzOt1ZLFbd5In5+LX4Z0QwzhUA+uyt\r\nCu17qrRiPt2JzALHjbkdV3OB5sbOSZDHl3aUuqll6Dg=\r\n-----END CERTIFICATE-----",
    "signatureTimestamp": "r/PzWEEgXyubXH/GCG6fLADU9Rz4e3b0KdZuNwfX/xk=",
    "responseTimestamp": "2023-03-20T09:12:38Z",
    "status": {
      "code": "OK",
      "message": "Signature generated successfully"
    }
  }
]
  • 8.1 eSignature with one-time certificate
  • POSTCreate a one time eSignature
  • 8.2 eSignature with user's eSignature creation device (SCD)
  • POSTCreate certificate
  • GETGet list of all user certificates
  • PATCHUpdate certificate status
  • POSTCreate a SCD eSignature using pseodonym
  • GETCreate a SCD eSignature with interactive pseodonym entry
  • GETGet pseodunym token
  • GETGet signature response
  • GETImplement eSignature callback API
  • 8.3 Audit log
  • GETAudit transactions

Create a one time eSignature

post

Use one time Certificate and keys created on the fly to make an eSignature

Path parameters
versionstringRequired

API version

Example: v1
Header parameters
X-GovStack-AuthenticationTokenstringRequired

JWT Authentication token received from ID BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
X-GovStack-PaymentTokenstringOptional

JWT Authentication token received from Payment BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Body
formatstring · enumOptional

Pre format the signature in a given format so that it can be inserted by the formatting library XAdES|CAdES|ASIC|JWS|PAdES

Example: PAdESPossible values:
hashstringOptional

hash as byte array encoded in base64

Example: 53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==
hashTypestring · enumOptional

hash type used SHA2-256|SHA2-384|SHA2-512|SHA3-256|SHA3-384|SHA3-512|BLAKE2B

Example: SHA2-256Possible values:
dataToBeDisplayedstringOptional

Data to be displayed on users SCD (for ex transactionId)

Example: Please sign the consent form as requested (transactionId: 1234)
requestTimestampstring · date-timeOptional

Timestamp in ISO 8601

Example: 2023-03-20T09:12:28Z
Responses
200
Signature response
application/json
400
Bad request
401
ID BB Authentication required
402
Payment required
404
Not found
422
Mandatory field not present
429
Too many requests
post
POST /{version}/sign/onetime HTTP/1.1
Host: localhost:9090
X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Content-Type: application/json
Accept: */*
Content-Length: 266

{
  "format": "PAdES",
  "hash": "53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==",
  "hashType": "SHA2-256",
  "dataToBeDisplayed": "Please sign the consent form as requested (transactionId: 1234)",
  "requestTimestamp": "2023-03-20T09:12:28Z"
}
{
  "signature": "53F4yGNsOXymuGL9JjF3Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==",
  "certificate": "-----BEGIN CERTIFICATE-----\r\nMIIDfDCCAmSgAwIBAgIQaSg0J93/hMMyFZ/DNEDM3DANBgkqhkiG9w0BAQsFADAp\r\nMScwJQYDVQQDDB5CLkVzdCBTb2x1dGlvbnMgU2lnbmluZyBQb3J0YWwwHhcNMjMw\r\nNDE0MTAzOTA5WhcNMjUwNzE3MTAzOTA5WjATMREwDwYDVQQDDAhKb2huIERvZTCC\r\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANU2fYwu2tz/D4GpTZZhPn4g\r\nFTH4TSbez1Ux9eMsmklYrmqdr3bBzJ4k8I1wkOBioxrXnH/s4zq7I1dJCbAsAzpd\r\niK8IBHo5XxwX2Num+HxRdU+nTOtfa4MZTGnvf4ZzLYBEK1lIsXQxAbMkPu4cBH8t\r\n9ir72GGU2qM/iMOv25eA75+cmNFj+02DohgpxXhErnZB/9mY+8oLvIFM5traf92U\r\nF4OPsepQYpJUM4u2prxbdcwVCmZ70FielcykaG7u84PRKbmAA50x2UQgsksThmxA\r\nPJlIvEoCS4BAAoLlY+ti0IFhThqYjG+FcRR5R48wa+oAJBquDG1eko6dTzp3BdEC\r\nAwEAAaOBtTCBsjAJBgNVHRMEAjAAMB0GA1UdDgQWBBR68RAciltftWZW4pAxqMQ0\r\nhigSEzBkBgNVHSMEXTBbgBRYpaezWi0heg09El0UypLU81uA4KEtpCswKTEnMCUG\r\nA1UEAwweQi5Fc3QgU29sdXRpb25zIFNpZ25pbmcgUG9ydGFsghQZ+B3m7iBv8Daf\r\nWiIkRB5NbVbQsTATBgNVHSUEDDAKBggrBgEFBQcDAjALBgNVHQ8EBAMCB4AwDQYJ\r\nKoZIhvcNAQELBQADggEBAI+5OAffnf3sn/jN58idSLUC09vWc6KPEzfZ2QLhDftq\r\nAfwSquItYFFuuQNh/x93HSprglDwL3U6sqRq0owMSSXXcLctVQr/MTEXyiRmQjUT\r\nHykwS/ovSw93E6VRnrF0qnaf6qOOAi0FfLxCV/1p3aEQBt7f/krZaW4Y33XrKi5F\r\nNnMhqQLtgZy9xXR0dNQ0ZKorEIptUrcujT8aRlEN4oqE7oo4j41TsksBQgEFfIeg\r\nljS6baoEko6n5ozyFzfeDWzd0yTzviXmUZGzOt1ZLFbd5In5+LX4Z0QwzhUA+uyt\r\nCu17qrRiPt2JzALHjbkdV3OB5sbOSZDHl3aUuqll6Dg=\r\n-----END CERTIFICATE-----",
  "signatureTimestamp": "r/PzWEEgXyubXH/GCG6fLADU9Rz4e3b0KdZuNwfX/xk=",
  "responseTimestamp": "2023-03-20T09:12:38Z",
  "status": {
    "code": "OK",
    "message": "Signature generated successfully"
  }
}

Create certificate

post

Create certificate on user's SCD (Signature Creation Device)

Path parameters
versionstringRequired

API version

Example: v1
Header parameters
X-GovStack-AuthenticationTokenstringRequired

JWT Authentication token received from ID BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
X-GovStack-PaymentTokenstringOptional

JWT Authentication token received from Payment BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Body
CSRstringOptional

Certificate Signing Request, in base64

SCDTypestring · enumOptional

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

Possible values:
SCDRemoteIdstringOptional

Device token (Android/Apple) for REMOTE_SCD_APP* and REMOTE_SCD_APP_SE*, for other TBD

SCDKeyIdnumberOptional

Key index to be used on SCD

pseodonymstringOptional

Optional pseodonym chosen by user

requestTimestampstring · date-timeOptional

Timestamp in ISO 8601

Responses
200
Certificate creation response
application/json
400
Bad request
401
ID BB Authentication required
402
Payment required
404
Not found
422
Mandatory field not present
429
Too many requests
post
POST /{version}/cert/create HTTP/1.1
Host: localhost:9090
X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Content-Type: application/json
Accept: */*
Content-Length: 1111

{
  "CSR": "-----BEGIN CERTIFICATE REQUEST-----\r\nMIICWDCCAUACAQAwEzERMA8GA1UEAwwISm9obiBEb2UwggEiMA0GCSqGSIb3DQEB\r\nAQUAA4IBDwAwggEKAoIBAQDVNn2MLtrc/w+BqU2WYT5+IBUx+E0m3s9VMfXjLJpJ\r\nWK5qna92wcyeJPCNcJDgYqMa15x/7OM6uyNXSQmwLAM6XYivCAR6OV8cF9jbpvh8\r\nUXVPp0zrX2uDGUxp73+Gcy2ARCtZSLF0MQGzJD7uHAR/LfYq+9hhlNqjP4jDr9uX\r\ngO+fnJjRY/tNg6IYKcV4RK52Qf/ZmPvKC7yBTOba2n/dlBeDj7HqUGKSVDOLtqa8\r\nW3XMFQpme9BYnpXMpGhu7vOD0Sm5gAOdMdlEILJLE4ZsQDyZSLxKAkuAQAKC5WPr\r\nYtCBYU4amIxvhXEUeUePMGvqACQargxtXpKOnU86dwXRAgMBAAGgADANBgkqhkiG\r\n9w0BAQsFAAOCAQEABmsIpQACArM5w7uQysuh6Aooe/fe6It9kYNccmHXf+Hta+i0\r\nzrXkOBZ80EuOFebuGzuc2R/cVpB4X6l9D6wNbn8Ee1NcnQOBb16U8Pjci9h24cVE\r\noDRAEJdae39ND4UFm4JAjiDfWO7cM0YtPkAAmtsY5ZWruReNVUsXJeco0fbIghuL\r\nhORaNIwEhw7zczpIDoQblNgaL7Tq4qpMPCf6hg+5KeoJEzQDlRBmLIrnFRTwCXpT\r\nDgWkOkbnsB1p4ebO/8RfD5sEmTIwiQHV2J71Ob6NMrBHbArZ79dyAdzuefQeRIhO\r\nLJEN4ipQLrwvjciJG9s48xEWrWrMNwT9AW+lWA==\r\n-----END CERTIFICATE REQUEST-----",
  "SCDType": "REMOTE_SCD_APP_ANDROID",
  "SCDRemoteId": "654C4DB3-3F68-4969-8ED2-80EA16B46EB0",
  "SCDKeyId": 0,
  "pseudonym": "johndoe5766",
  "requestTimestamp": "2023-03-20T09:12:28Z"
}
{
  "certificateId": "09440694c5c1798a23aad320abcd04b83f02f5ea12b8865df073d0e77ad5ae27",
  "pseudonym": "johndoe5766",
  "certificate": "-----BEGIN CERTIFICATE-----\r\nMIIDfDCCAmSgAwIBAgIQaSg0J93/hMMyFZ/DNEDM3DANBgkqhkiG9w0BAQsFADAp\r\nMScwJQYDVQQDDB5CLkVzdCBTb2x1dGlvbnMgU2lnbmluZyBQb3J0YWwwHhcNMjMw\r\nNDE0MTAzOTA5WhcNMjUwNzE3MTAzOTA5WjATMREwDwYDVQQDDAhKb2huIERvZTCC\r\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANU2fYwu2tz/D4GpTZZhPn4g\r\nFTH4TSbez1Ux9eMsmklYrmqdr3bBzJ4k8I1wkOBioxrXnH/s4zq7I1dJCbAsAzpd\r\niK8IBHo5XxwX2Num+HxRdU+nTOtfa4MZTGnvf4ZzLYBEK1lIsXQxAbMkPu4cBH8t\r\n9ir72GGU2qM/iMOv25eA75+cmNFj+02DohgpxXhErnZB/9mY+8oLvIFM5traf92U\r\nF4OPsepQYpJUM4u2prxbdcwVCmZ70FielcykaG7u84PRKbmAA50x2UQgsksThmxA\r\nPJlIvEoCS4BAAoLlY+ti0IFhThqYjG+FcRR5R48wa+oAJBquDG1eko6dTzp3BdEC\r\nAwEAAaOBtTCBsjAJBgNVHRMEAjAAMB0GA1UdDgQWBBR68RAciltftWZW4pAxqMQ0\r\nhigSEzBkBgNVHSMEXTBbgBRYpaezWi0heg09El0UypLU81uA4KEtpCswKTEnMCUG\r\nA1UEAwweQi5Fc3QgU29sdXRpb25zIFNpZ25pbmcgUG9ydGFsghQZ+B3m7iBv8Daf\r\nWiIkRB5NbVbQsTATBgNVHSUEDDAKBggrBgEFBQcDAjALBgNVHQ8EBAMCB4AwDQYJ\r\nKoZIhvcNAQELBQADggEBAI+5OAffnf3sn/jN58idSLUC09vWc6KPEzfZ2QLhDftq\r\nAfwSquItYFFuuQNh/x93HSprglDwL3U6sqRq0owMSSXXcLctVQr/MTEXyiRmQjUT\r\nHykwS/ovSw93E6VRnrF0qnaf6qOOAi0FfLxCV/1p3aEQBt7f/krZaW4Y33XrKi5F\r\nNnMhqQLtgZy9xXR0dNQ0ZKorEIptUrcujT8aRlEN4oqE7oo4j41TsksBQgEFfIeg\r\nljS6baoEko6n5ozyFzfeDWzd0yTzviXmUZGzOt1ZLFbd5In5+LX4Z0QwzhUA+uyt\r\nCu17qrRiPt2JzALHjbkdV3OB5sbOSZDHl3aUuqll6Dg=\r\n-----END CERTIFICATE-----",
  "responseTimestamp": "2023-03-20T09:12:38Z",
  "status": {
    "code": "OK",
    "message": "Certificate generated successfully"
  }
}

Update certificate status

patch

Update certificate status

Path parameters
versionstringRequired

API version

Example: v1
certificateIdstringRequired

certificateId that indicates the certificate to be updated

Example: 09440694c5c1798a23aad320abcd04b83f02f5ea12b8865df073d0e77ad5ae27
Header parameters
X-GovStack-AuthenticationTokenstringRequired

JWT Authentication token received from ID BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Body
requestTimestampstring · date-timeOptional

Timestamp in ISO 8601

Responses
200
Update certificate response
application/json
400
Bad request
401
ID BB Authentication required
404
Not found
422
Mandatory field not present
429
Too many requests
patch
PATCH /{version}/cert/{certificateId} HTTP/1.1
Host: localhost:9090
X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Content-Type: application/json
Accept: */*
Content-Length: 136

{
  "requestTimestamp": "2023-03-20T09:12:28Z",
  "status": {
    "code": "SUSPENDED",
    "message": "Certificate to be suspended because of user action"
  }
}
{
  "responseTimestamp": "2023-03-20T09:12:38Z",
  "status": {
    "code": "SUSPENDED",
    "message": "Certificate supended because of user action on 02.02.2023"
  }
}

Create a SCD eSignature using pseodonym

post

Use user's SCD (Signature Creation Device) to create an eSignature

Path parameters
versionstringRequired

API version

Example: v1
Header parameters
X-Pseodonym-TokenstringOptional

JWT pseudonym token

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA
Body
formatstring · enumOptional

Pre format the signature in a give format so that it can be inserted by the formatting library XAdES|CAdES|ASIC|JWS|PAdES

Example: PAdESPossible values:
hashstringOptional

hash as byte array encoded in base64

Example: 53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==
hashTypestring · enumOptional

hash type used SHA2-256|SHA2-384|SHA2-512|SHA3-256|SHA3-384|SHA3-512|BLAKE2B

Example: SHA2-256Possible values:
dataToBeDisplayedstringOptional

Data to be displayed on users SCD (for ex transactionId)

Example: Please sign the consent form as requested (transactionId: 1234)
noncestringOptional

hex string value of hash to mitigate replay attacks

Example: d2dff00401c92ca6879ef5f0938ce31580898266d59832d8531e8d04fc3898a6
statestringOptional

hex string value of hash used to maintain state between the request and the callback

Example: 2569cb4125cb7303f0f16782e7e2814b2269888c734af4c90639653e4f92d3a5
requestTimestampstring · date-timeOptional

Timestamp in ISO 8601

Example: 2023-03-20T09:12:28Z
Responses
200
Signature response
application/json
302
Redirect to /sign/interactivePseudonym if X-Pseodonym-Token not present
400
Bad request
404
Not found
422
Mandatory field not present
429
Too many requests
post
POST /{version}/sign/pseudonym HTTP/1.1
Host: localhost:9090
Content-Type: application/json
Accept: */*
Content-Length: 416

{
  "format": "PAdES",
  "hash": "53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==",
  "hashType": "SHA2-256",
  "dataToBeDisplayed": "Please sign the consent form as requested (transactionId: 1234)",
  "nonce": "d2dff00401c92ca6879ef5f0938ce31580898266d59832d8531e8d04fc3898a6",
  "state": "2569cb4125cb7303f0f16782e7e2814b2269888c734af4c90639653e4f92d3a5",
  "requestTimestamp": "2023-03-20T09:12:28Z"
}
{
  "signatureId": "7607fa7f45b2558201baf05215521a7df63078774f0b0d1ad15ccfcb0aad9484",
  "responseTimestamp": "2023-03-20T09:12:38Z",
  "status": {
    "code": "OK",
    "message": "Signature generated successfully"
  }
}