Integration guidelines of eZīmogs+ Cloud

Requirements for integrating eZīmogs+ Cloud into your system

Follow this flow to seal a document with eZīmogs+ Cloud using SignAPI and the eParaksts integration platform.

ℹ️
The SignAPI eSealCreate method is not applicable to eZīmogs+ Cloud.

Prerequisites

Before you start, make sure you can:

access the e-Identity and Signing Platform, SignAPI
access the eParaksts integration platform at eidas.eparaksts.lv
obtain the end user’s authentication certificate
obtain the end user’s qSeal certificate
authenticate backend requests using your integration credentials

The end user is a natural person authorized to seal documents on behalf of the company.

Happy-path flow

Step	Action	Result
1	Obtain the end user certificates	You have the authentication certificate and qSeal certificate
2	Request a server-to-server access token	You receive an introspect token
3	Start a SignAPI session	A signing session is created
4	Upload the file and calculate signable data	Signable data is prepared using the qSeal certificate
5	Create the digital seal	You receive the signature value
6	Finalize the sealing process	The seal is applied to the document
7	Download and validate the sealed document	You have the final sealed document

1. Obtain the end user certificates

Obtain the certificates required for the sealing process.

You need access to:

the end user’s authentication certificate
the end user’s qSeal certificate

Use one of the following methods to obtain the authentication certificate:

Authentication method	How to obtain the certificate
eParaksts mobile	Use the eParaksts integration platform at `eidas.eparaksts.lv`
eID card	Use the browser plugin that reads certificates from the smart card reader

The qSeal certificate is used later to calculate the signable data.

2. Request an introspect token

After obtaining the end user certificates, use the eParaksts integration platform together with your credentials to perform a backend request.

The response contains a server-to-server access token, also called an introspect token.

Use this token to authenticate requests to the SignAPI service.

3. Start a SignAPI session

Authenticate to SignAPI using the introspect token.

Then start a SignAPI session for the document sealing process.

4. Upload the file and calculate signable data

Upload the file to SignAPI.

Then calculate the signable data using the qSeal certificate obtained in step 1.

The signable data is required before the digital seal can be created.

5. Create the digital seal

Create the digital seal using the eParaksts integration platform at eidas.eparaksts.lv.

Use one of the following methods:

POST /trustedx-resources/esigp/v1/signatures/server/raw

POST /trustedx-resources/esigp/v1/signatures/server/batch

6. Finalize the sealing process

Finalize the document sealing process using:

the end user’s authentication certificate, either eID or eParaksts mobile
the signature value received in the previous step

After this step, the digital seal is applied to the document.

7. Download and validate the sealed document

Download the sealed document from SignAPI.

Validate the sealed document before returning it to the end user or storing it in your system.

Useful hints

Signing identity types

There are four types of signing identity:

Signing identity type	Purpose
Mobile identity for advanced electronic signing	Used for advanced electronic signing with eParaksts mobile
Mobile identity for authentication	Used for authentication with eParaksts mobile
Server identity for qualified electronic signing, `serverid`	Used for qualified electronic signing
Qualified electronic seal identity, qsealc	Used for qualified electronic sealing with eZīmogs+ Cloud

One user can have multiple qsealc identities.

Legal person seal identities

Legal person seal identities are identities with a legal person qualified e-seal certificate.

A user token can contain zero, one, or multiple legal person seal identities. All Common Name (CN) labels are unique.

Each legal person seal identity must contain the following labels:

Label	Description
`eparaksts`	eParaksts identity label
`qsealc`	Qualified electronic seal certificate label
`CN:<certificate common name>`	Certificate Common Name value
`x509:keyUsage:contentCommitment`	Indicates that the certificate can be used for signing or sealing

To select the required signing identity, enumerate the mandatory CN:<certificate common name> label values and use them to build a list of available signing identities.

User password input dialog

In the password input dialog, the certificate Common Name (CN) value is shown to help the user understand which certificate password is being requested.

Examples:

Certificate type	Example value shown to the user
Individual signature certificate	`MĀRA PARAUDZIŅA`
eZīmogs+ Cloud certificate	`SIA PARAUDZIŅŠ (ACCOUNTING): eZīmogs`

Signing identity labels for eZīmogs+ Cloud

The available signing identities are labeled with tags. For eZīmogs+ Cloud, use the qsealc label to identify qualified electronic seal identities.

Example labels for an eZīmogs+ Cloud identity:

[
  "eparaksts",
  "qsealc",
  "qsealcVersion1",
  "x509:keyUsage:contentCommitment",
  "SIA PARAUDZIŅŠ (RAŽOŠANA) : eZīmogs"
]

User token sample

Full user token sample

{
  "_omitted_before": "...",
  "sign_identities": [
    {
      "access": [
        {
          "user_id": "efc651efcdec32f1e6cab9dc0f0cdf60"
        }
      ],
      "domain": "citizen",
      "self": "https://eparaksts/trustedx-resources/esigp/v1/sign_identities/sqnd2nvpkr0siar572hi8a9t1h",
      "description": "eparaksts:qsealc:sign",
      "links": {
        "Signatures.create.server.raw": {
          "auth": {
            "oauth2": {
              "scopes": [
                "urn:safelayer:eidas:sign:identity:use:server"
              ]
            }
          }
        }
      },
      "id": "sqnd2nvpkr0siar572hi8a9t1h",
      "type": "pki:x509",
      "labels": [
        "qsealc",
        "qsealcVersion1",
        "CN:SIA DEMO QSEALC (Testēšana) : eZīmogs",
        "x509:keyUsage:contentCommitment",
        "eparaksts",
        "tknid:nRI7j+e/FlfLFmFB/3L15cmhdmA="
      ],
      "status": {
        "value": "enabled"
      }
    },
    {
      "access": [
        {
          "user_id": "efc651efcdec32f1e6cab9dc0f0cdf60"
        }
      ],
      "domain": "citizen",
      "self": "https://eparaksts/trustedx-resources/esigp/v1/sign_identities/fmc8755q6fgqg341jlo7pkucm5",
      "description": "eparaksts:qsealc:sign",
      "links": {
        "Signatures.create.server.raw": {
          "auth": {
            "oauth2": {
              "scopes": [
                "urn:safelayer:eidas:sign:identity:use:server"
              ]
            }
          }
        }
      },
      "id": "fmc8755q6fgqg341jlo7pkucm5",
      "type": "pki:x509",
      "labels": [
        "qsealc",
        "qsealcVersion1",
        "CN:SIA DEMO QSEALC : eZīmogs",
        "x509:keyUsage:contentCommitment",
        "tknid:nwUFDyZk5kTrLa9gJijd5bS+PPM=",
        "eparaksts"
      ],
      "status": {
        "value": "enabled"
      }
    },
    {
      "access": [
        {
          "user_id": "efc651efcdec32f1e6cab9dc0f0cdf60"
        }
      ],
      "device_id": "3ae81f567fbe23cbb672a7b1e9b30d5db2793b4d",
      "domain": "citizen",
      "self": "https://eparaksts/trustedx-resources/esigp/v1/sign_identities/v05nvkmq3lgjh4f6n2naoe7aee",
      "description": "eparaksts:mobileid:auth",
      "id": "v05nvkmq3lgjh4f6n2naoe7aee",
      "type": "pki:x509",
      "labels": [
        "mobileidVersion2",
        "mobileid",
        "x509:keyUsage:digitalSignature",
        "eparaksts"
      ],
      "status": {
        "value": "enabled"
      }
    },
    {
      "access": [
        {
          "user_id": "efc651efcdec32f1e6cab9dc0f0cdf60"
        }
      ],
      "device_id": "3ae81f567fbe23cbb672a7b1e9b30d5db2793b4d",
      "domain": "citizen",
      "self": "https://eparaksts/trustedx-resources/esigp/v1/sign_identities/7rifb8vo8msc54f3nbfu9hv96h",
      "description": "eparaksts:mobileid:sign",
      "id": "7rifb8vo8msc54f3nbfu9hv96h",
      "type": "pki:x509",
      "labels": [
        "mobileidVersion2",
        "mobileid",
        "x509:keyUsage:contentCommitment",
        "eparaksts"
      ],
      "status": {
        "value": "enabled"
      }
    },
    {
      "access": [
        {
          "user_id": "efc651efcdec32f1e6cab9dc0f0cdf60"
        }
      ],
      "domain": "citizen",
      "self": "https://eparaksts/trustedx-resources/esigp/v1/sign_identities/7mmprhva8url12kk1vauj2ikuj",
      "description": "eparaksts:serverid:sign",
      "links": {
        "Signatures.create.server.raw": {
          "auth": {
            "oauth2": {
              "scopes": [
                "urn:safelayer:eidas:sign:identity:use:server"
              ]
            }
          }
        }
      },
      "id": "7mmprhva8url12kk1vauj2ikuj",
      "type": "pki:x509",
      "labels": [
        "tknid:GqiMOC71ahoIeMNJUsDWicFANAw=",
        "serveridVersion1",
        "x509:keyUsage:contentCommitment",
        "CN:ANDRIS PARAUDZIŅŠ",
        "eparaksts",
        "serverid"
      ],
      "status": {
        "value": "enabled"
      }
    }
  ],
  "_omitted_after": "..."
}

Requirements for integrating eZīmogs+ Cloud into your system

Prerequisites

Happy-path flow

1. Obtain the end user certificates

2. Request an introspect token

3. Start a SignAPI session

4. Upload the file and calculate signable data

5. Create the digital seal

6. Finalize the sealing process

7. Download and validate the sealed document

Related documentation

Useful hints

Signing identity types

Legal person seal identities

User password input dialog

Signing identity labels for eZīmogs+ Cloud

User token sample