8 Service APIs

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.

8.1 eSignature with one-time certificate

Create a one time eSignature

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

post

/{version}/sign/onetime

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

JWT Authentication token received from Payment BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA

Body

hashstring

hash as byte array encoded in base64

Example: 53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==

dataToBeDisplayedstring

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

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

requestTimestampstring · date-time

Timestamp in ISO 8601

Example: 2023-03-20T09:12:28Z

formatstring · enum

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

Example: PAdES

Options: XAdES, CAdES, ASIC, JWS, PAdES

hashTypestring · enum

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

Example: SHA2-256

Options: SHA2-256, SHA2-384, SHA2-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2B

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'http://localhost:9090/{version}/sign/onetime' \
  --header 'X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA' \
  --header 'Content-Type: application/json' \
  --data '{"hash":"53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==","dataToBeDisplayed":"Please sign the consent form as requested (transactionId: 1234)","requestTimestamp":"2023-03-20T09:12:28Z","format":"PAdES","hashType":"SHA2-256"}'

200

400

401

402

404

422

429

200

{
  "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"
  }
}

Signature response

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

8.2.1 Certificate creation

Create certificate

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

post

/{version}/cert/create

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

JWT Authentication token received from Payment BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA

Body

CSRstring

Certificate Signing Request, in base64

SCDRemoteIdstring

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

SCDKeyIdnumber

Key index to be used on SCD

pseodonymstring

Optional pseodonym chosen by user

requestTimestampstring · date-time

Timestamp in ISO 8601

SCDTypestring · enum

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

Options: REMOTE_SCD_APP_APPLE, REMOTE_SCD_APP_ANDROID, REMOTE_SCD_APP_SE_APPLE, REMOTE_SCD_APP_SE_ANDROID, REMOTE_SCD_SIM, REMOTE_SCD_ESIM

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'http://localhost:9090/{version}/cert/create' \
  --header 'X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA' \
  --header 'Content-Type: application/json' \
  --data '{"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"}'

200

400

401

402

404

422

429

200

{
  "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"
  }
}

Certificate creation response

8.2.2 List certificates

Get list of all user certificates

Get list of all user certificates

get

/{version}/cert/list

Path parameters

versionstringrequired

API version

Example: v1

Query parameters

filterstring · enum

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

Example: ALL

Options: ALL, ACTIVATED, EXPIRED, REVOKED, SUSPENDED

Header parameters

X-GovStack-AuthenticationTokenstringrequired

JWT Authentication token received from ID BB

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:9090/{version}/cert/list' \
  --header 'X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA'

200

400

404

422

429

200

[
  {
    "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"
    }
  }
]

List certificates response

8.2.3 Update certificate

Update certificate status

Update certificate status

patch

/{version}/cert/{certificateId}

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

Timestamp in ISO 8601

statusobject

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'http://localhost:9090/{version}/cert/{certificateId}' \
  --header 'X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA' \
  --header 'Content-Type: application/json' \
  --data '{"requestTimestamp":"2023-03-20T09:12:28Z","status":{"code":"SUSPENDED","message":"Certificate to be suspended because of user action"}}'

200

400

401

404

422

429

200

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

Update certificate response

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

8.2.4 eSignature with user's device

Create a SCD eSignature using pseodonym

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

post

/{version}/sign/pseudonym

Path parameters

versionstringrequired

API version

Example: v1

Header parameters

X-Pseodonym-Tokenstring

JWT pseudonym token

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA

Body

hashstring

hash as byte array encoded in base64

Example: 53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==

dataToBeDisplayedstring

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

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

noncestring

hex string value of hash to mitigate replay attacks

Example: d2dff00401c92ca6879ef5f0938ce31580898266d59832d8531e8d04fc3898a6

statestring

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

Example: 2569cb4125cb7303f0f16782e7e2814b2269888c734af4c90639653e4f92d3a5

requestTimestampstring · date-time

Timestamp in ISO 8601

Example: 2023-03-20T09:12:28Z

formatstring · enum

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

Example: PAdES

Options: XAdES, CAdES, ASIC, JWS, PAdES

hashTypestring · enum

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

Example: SHA2-256

Options: SHA2-256, SHA2-384, SHA2-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2B

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'http://localhost:9090/{version}/sign/pseudonym' \
  --header 'Content-Type: application/json' \
  --data '{"hash":"53F4yGNsOXymuGL9JjF3/Qi377pQVLqkDZuc1shPJB3xFJHJnhW8yepjhU8ILTz/wYoahXnzKj8xyT7PtbtwEA==","dataToBeDisplayed":"Please sign the consent form as requested (transactionId: 1234)","nonce":"d2dff00401c92ca6879ef5f0938ce31580898266d59832d8531e8d04fc3898a6","state":"2569cb4125cb7303f0f16782e7e2814b2269888c734af4c90639653e4f92d3a5","requestTimestamp":"2023-03-20T09:12:28Z","format":"PAdES","hashType":"SHA2-256"}'

200

302

400

404

422

429

200

{
  "signatureId": "7607fa7f45b2558201baf05215521a7df63078774f0b0d1ad15ccfcb0aad9484",
  "responseTimestamp": "2023-03-20T09:12:38Z",
  "status": {
    "code": "OK",
    "message": "Signature generated successfully"
  }
}

Signature response

8.2.5 Webservice to enter user pseudonym

Create a SCD eSignature with interactive pseodonym entry

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

get

/{version}/sign/interactivePseudonym

Path parameters

versionstringrequired

API version

Example: v1

Query parameters

formatstring · enum

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: PAdES

Options: XAdES, CAdES, ASIC, JWS, PAdES

hashstring · base64urlencoded

hash as byte array encoded in base64

Example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

hashTypestring · enum

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

Example: SHA2-256

Options: SHA2-256, SHA2-384, SHA2-512, SHA3-256, SHA3-384, SHA3-512, BLAKE2B

dataToBeDisplayedstring · base64urlencoded

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

Example: UGxlYXNlIHNpZ24gdGhlIGNvbnNlbnQgZm9ybSBhcyByZXF1ZXN0ZWQgKHRyYW5zYWN0aW9uSWQ6MTIzNCk

requestTimestampstring · urlencoded

Timestamp in ISO 8601

Example: 2023-03-20T09%3A12%3A28Z

noncestring · urlencoded

hex string value of hash to mitigate replay attacks

Example: d2dff00401c92ca6879ef5f0938ce31580898266d59832d8531e8d04fc3898a6

statestring · urlencoded

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

Example: 2569cb4125cb7303f0f16782e7e2814b2269888c734af4c90639653e4f92d3a5

callbackUrlstring · urlencoded

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

text/html

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:9090/{version}/sign/interactivePseudonym'

200

400

404

422

429

200

text

Returns html for entering pseudonym

8.2.6 User pseudonym API

Get pseodunym token

In order not to get the pseodonym token internally

get

/{version}/token/pseodonym/{pseudonym}

Path parameters

versionstringrequired

API version

Example: v1

pseudonymstringrequired

Unique pseudonym

Example: johndoe5766

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:9090/{version}/token/pseodonym/{pseudonym}'

200

400

404

422

429

200

{
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA"
}

Pseodonym token generated successfully

8.2.7 Get signature response

Get signature response

In order not to get the pseodonym token internally

get

/{version}/sign/response/{signatureId}

Path parameters

versionstringrequired

API version

Example: v1

signatureIdstringrequired

get signature response for signatureId

Example: 7607fa7f45b2558201baf05215521a7df63078774f0b0d1ad15ccfcb0aad9484

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:9090/{version}/sign/response/{signatureId}'

200

400

404

422

429

200

{
  "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"
  }
}

Signature response

8.2.8 Callback service API

Implement eSignature callback API

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

get

/{version}/esignature/callback

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

text/html

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:9090/{version}/esignature/callback?signatureId=7607fa7f45b2558201baf05215521a7df63078774f0b0d1ad15ccfcb0aad9484&nonce=text&state=text'

200

200

text

Returns html for continuing user's flow

8.3 Audit log

Audit transactions

Way for users and auditors to review the signature requests made

get

/{version}/audit/log

Path parameters

versionstringrequired

API version

Example: v1

Query parameters

startstring · urlencoded

Timestamp in ISO 8601

Example: 2023-03-20T09%3A12%3A28Z

endstring · urlencoded

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

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:9090/{version}/audit/log' \
  --header 'X-GovStack-AuthenticationToken: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjcyNzcyYzI5OGNkZDNmYmQ3YmQxNmI5NTAxZDY0ODdiIn0.eyJwdWIiOiJKb2huIERvZSJ9.zNNhLDuydPHC7-YQYDhaGTaqS-efAL79pJXdWWm5Y7Fd94fVRCLvRTaA16ffQyhYPXHKcx8Q9baTB_fX0PtBuA'

200

400

401

404

422

429

200

[
  {
    "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"
    }
  }
]

Audit response