Kopjra is an Italian legal tech company, ISO 27001 certified, working on the design and development of innovative and cost-effective trust services and electronic signatures. Our patented technology follows the ISO 27037 international digital forensic standard, which details the guidelines for identification, collection, acquisition and preservation of digital evidence.

Web Trust (WT) is a suite of API solutions for electronically signing documents, webpages, and data flows. The main scope of most of the solutions is to sign an interaction between two parties over the Internet using a proprietary and patented technology. Web Trust’s solutions cover six possible workflows respectively, each of which could be integrated into a company process:

• Document Advanced: API solution to fill-in and sign any PDF document such as policies and contracts using an Advanced Electronic Signature (AES). It identifies the signer using SPID (Sistema Pubblico di Identità Digitale).
• Document Simple Forensic: API solution to fill-in and sign any PDF document such as policies and contracts. It identifies the signer using an OTP (One Time Password) via SMS. Each signature interaction takes place within an isolated environment that acquires it forensically using a patented methodology owned by Kopjra.
• Document Simple: API solution to fill-in and sign any PDF document such as policies and contracts.
• Webpage Forensic: API solution to apply a click-to-sign electronic signature on a note, policy or contract published on a webpage. Each signature interaction takes place within an isolated environment that acquires it forensically using a patented methodology owned by Kopjra.
• Data Forensic: API solution to electronically sign data flows coming from application and/or IoT (Internet of Things) devices. Each signature interaction takes place within an isolated environment that acquires it forensically using a patented methodology owned by Kopjra.
• Timestamp: API solution to apply qualified or trustless timestamps to documents or log files. With trustless we intend the notarization over the Bitcoin blockchain.

The UI (User Interface) of our solutions was designed to be fully responsive, allowing a seamless experience both in desktop and mobile devices, using WebView and WKWebView components available on Android and iOS SDKs.

The following table will show the main differences (features, probative value, etc.) between each API solution introduced above:

We are also offering a complete SaaS solution based on our Document Simple Forensic API, Web Sign, for professionals and companies who need a ready to use DTM (Digital Transaction Management) platform.

WT offers a set of endpoints that allow you to interact with the system. These endpoints are hosted at the following URL: https://api.webtrust.kopjra.com/v1. The following documentation will guide you through the available endpoints and their functionalities.

Preceding a manual activation on our part the user may also have access to a DEMO environment hosted at https://api-demo.webtrust.kopjra.com. This environment is a mirror of the production one and it is meant to be used for testing purposes only. The data stored in the DEMO environment is not guaranteed to be persistent. DEMO is not activated by default, if you need access to it please contact our support team.

WT offers http basic authentication to allow access to its API. You can register new WT credentials at our developer portal. WT expects for the credentials to be included in all API requests to the server in a header Authorization.

Some special users will have the capacity to perform certain API calls as if they were made by another user, thus impersonating that other user. The impersonation capacity is rather powerful and it is given only to certain users directly by the system administrators. From now on we will call the user that is trying to impersonate another, the impersonator. Impersonation takes place when the API call contains the following header (besides the Authorization one):

X-Impersonate-User: <externalUserId>

With the concept of impersonation the user can be distributed into two (not necessarily) exclusive layers: the users that can be impersonated and the users that can impersonate other users (impersonators). An impersonator generally manages its own users and has a way to identify them in his/her own systems, this identification is what we called the externalUserId and it is the one that has to be provided when impersonating.

This impersonation header will instruct WT to:

1. Verify whether externalUserId identifies a user that can be impersonated by the impersonator that is making the API call.
2. If yes then proceed with the API call as the impersonated user

if there is no user corresponding to that externalUserId then the system will automatically create one and will link it to the impersonator.

Archetypes describe the tags schema that a set of your interactions must adhere to, in order to be created. For example, if you want to split all of your interactions in 2 partitions (one for privacy policies and one for contracts), you can define two different archetypes. In the first one, you will specify all the meaningful tags for privacy policies (eg: an identifier of the signer and the version of your privacy policy) and in the second one you will specify all the meaningful tags for contracts (eg: an identifier of the signer, the version of the contract, and your company's associate that signed the contract on its behalf).

Later on, when you will create interactions, you should specify the relevant archetypeId in the body of the create request and the system will prevent you to create an interaction with a meaningful archetypeId if its associated tags do not respect the schema indicated in the archetype.

This solution offers an alternative to the "Document" ones, that allows a company to create interactions to apply click-to-sign electronic signatures. In this case the company may want to sign a contract or policy but in this case they won’t be within a PDF document but inside a web page.

Integrating this solution requires a little bit more effort since the signature interaction takes place inside a web page that must be rendered by the company before being presented to the signer.

Let's take into account the following initial scenario:

This diagram shows a fairly common use case where a user interacts with a server-side rendered web page.

1. The user opens an URL pointing to a web page of the company;
2. The web page is then rendered at the server and served to the user;
3. At this point the user interacts with the web page (e.g. fills a form) and finally submits an action to the server at the company;
4. The server sends back a response to the user regarding the submitted action.

However, assume that the company wants to present in that web page a contract that needs to be signed with at least a Simple Electronic Signature (SES). The Webpage Forensic API allows the company to produce a SES with forensic probative value using proprietary and patented methodology that creates a forensic layer following the standard ISO/IEC 27037:2012, all of this without disrupting the company’s user experience. Therefore, for the signer it would be like nothing changed, but the company will have a strong signature that could be used irrefutably to prove that the interaction took place, in case of litigation. The following diagram shows, at a certain level of abstraction, how the interaction takes place once WT is integrated within the company's process.

1. The user opens an URL pointing to a web page of the company.
2. The company's web server, instead of responding right away, will create a new interaction using the WT endpoint createInteraction with the property variation set to full (the default value). The interaction object will contain a pre-rendered HTML page (the very same page that the company would have sent directly to the user) along with the URL where the company intends to handle the user's action (O-URL).

   The user's action must be sent to the WT gateway before reaching its final destination. Therefore, the company needs to specify O-URL as a parameter while creating a new interaction. For the same reason, the company must replace O-URL within the pre-rendered HTML with the placeholder <%= e_url %>.

   For instance, if the user's action is the submission of a form and O-URL is http://company_webserver.com/submit the company has to:

   • Replace <form action="http://company_webserver.com/submit" method="post"> with <form action="<%= e_url %>" method="post"> inside the pre-rendered HTML the company will provide to WT,
   • Specify http://company_webserver.com/submit as the parameter O-URL and full as the parameter variation. More details on these parameters can be found in the create interaction [operation/createInteraction] section.

3. WT initialises the new interaction object. This object will represent the interaction that should take place between the user and the company's Web Server.
4. The WT gateway will return such an interaction object to the caller. The returned object contains the Id of the newly created interaction and the forwarding URL (F-URL) to which the company's Web Server must redirect the user.
5. The company's Web Server responds to the HTTP request sent by the user in step 1 with an HTTP Redirection to F-URL.
6. The user's browser reaches the F-URL endpoint in the WT gateway. This endpoint does not contain the actual page.
7. The WT gateway requests the corresponding interaction for the effective URL (E-URL) where the page will be served.
8. Under the hood, the previous step will indicate our system to initialise an isolated secured container to serve the effective page. The container will immediately start a forensic acquisition session.
9. The E-URL is returned to the WT gateway.
10. The WT gateway will respond to the user's request in step 6 with an HTTP Redirection to E-URL.
11. The user's browser visits the E-URL served from the secured container.
12. The secured container responds with the page. Note: This page is built using the pre-rendered HTML replacing the placeholder using an URL served from the secured container.
13. The user interacts with the page (e.g. fills a form) and finally submits an action (e.g. submits the form).
14. This submission will go directly to the secured container and an HTTP Redirection (of the submitted action) to O-URL will be sent back to the user's browser.
15. The secured container will conclude the acquisition session started in step 8.
16. The corresponding interaction will be updated accordingly, reflecting the acquisition status and all the gathered data.
17. Due to the redirection in step 14 the user's browser will resubmit the action to O-URL, served by the company.
18. The company's Web Server sends a proper response to the user.

This extended process proposed by WT is an expansion of the normal interaction that would have taken place between the user and the company. Note that those are steps 1, 12, 17 and 18 of the previous diagram.

This solution allows a company to sign data flows coming from Single Page Applications (SPA), Native Applications or IoT (Internet of things) devices; also in this case the signatures happen within a forensic environment using a proprietary and patented methodology following the standard ISO/IEC 27037:2012. The key difference between this solution and the Webpage Forensic API is that in this case the context that produces the signature is not acquired forensically.

This workflow defines how to use WT to acquire a user's API call directed to the company's Web Server. For instance, an API call coming from a Single Page Application (SPA). The acquisition will include only the user's action that provoked an API call from the SPA. However, it will not include any context whatsoever (i.e. the SPA itself).

Let's take into account the following initial scenario:

The previous image shows a simple interaction between a user and a company via an API call, which in this case originated from an SPA.

1. The user opens a company's URL, from the SPA is being served;
2. The SPA is sent to the user's browser;
3. At this point the user interacts with the SPA (e.g. moves around and eventually fills a form) and finally submits an action to the server via an API call originating from the SPA;
4. The server sends back a response to the user regarding the submitted action and the SPA is updated accordingly.

Steps 1 and 2 are out of WT's scope. Hence we will focus from the moment of the API call onwards, losing this way any context the user may have had before submitting the action.

Let's assume the company wants to forensically sign the interaction that occurs between the user and the company's web server via an API call originating from the SPA.

The following diagram shows at a certain level of abstraction how the interaction takes place once WT is integrated within the company's process.

In the previous diagram there is no reference to the fact that the user opened and interacted with the SPA. Since those actions are out of WT' scope we will start from the moment the API call originated.

1. The user, while interacting with the SPA, triggers a specific action that informs the company's Web Server that he is willing to do (or it is very likely that he will do) a specific request that the company wants to acquire using WT. Note: at this point, the company must prevent the user from doing the action that triggers the request the company wants to acquire with WT.
2. The company's Web Server, instead of responding right away, will create a new interaction using the endpoint createInteraction specifying the property variation with value no_html. The user's Request that the company wants to acquire with WT has to be sent to WT before reaching its final destination in the company's Web Server. It is paramount that the company specifies the O-URL as a parameter in the interaction creation, so when the process is concluding, WT can redirect the request to this Url.
3. WT initialises the new interaction object. This object will represent the interaction that should take place between the user and the company's Web Server.
4. The WT gateway will return such an interaction object to the caller. The returned object contains the Id of the newly created interaction and the forwarding URL (F-URL) to which the company's Web Server must redirect the user's API call.
5. The company's Web Server responds to the HTTP request sent by the user via the SPA in step 1 with an HTTP Redirection to F-URL. The redirection can be done in two possible ways,

• the first one implies a prior modification of the SPA. Assuming the API call is done from a button event handler, the following can be done:

          async function eventHandler(...) { ...
  
          // call the endpoint that will provoke the interaction creation let interactionResponse = await fetch(COMPANY_WEB_SERVER_URL, options);
  
          // call the F-URL endpoint in the WT gateway let realResponse = await fetch(interactionResponse.fUrl, options);
  
          ... }
  

• the second way uses the HTTP redirection mechanism. Using this way, the SPA does not need to be modified. However, it is necessary that the company's Web Server responds with an HTTP Redirect to F-URL using the HTTP code 307 to ensure the preservation of the method as well as the body.

6. The action is then resubmitted to the F-URL endpoint in the WT gateway.
7. At that point the WT gateway asks the corresponding interaction for the effective URL (E-URL). This Url will be an endpoint within WT, to where the action will be redirected in order to perform a forensic acquisition.
8. The previous action will indicate our system to initialise a secured container to serve the effective page. The container will immediately start a forensic acquisition session.
9. The E-URL is then returned to the WT gateway.
10. The WT gateway will respond to the user's request in step 6 with an HTTP Redirection to E-URL using code 307.
11. The action gets resubmitted this time to the E-URL served from the secured container.
12. An HTTP Redirection (of the submitted action) to O-URL will be sent back to the user's browser.
13. The secured container will conclude the acquisition session started in step 8.
14. The corresponding interaction will be updated accordingly, reflecting the acquisition status and all the gathered data.
15. Due to the redirection in step 14 the user's browser will resubmit the action to O-URL served by the company.
16. The company's Web Server sends a proper response to the user.

This extended process proposed by WT is an expansion of the normal interaction that would have taken place between the user and the company. Note that those are steps 1 and 16 of the previous flow.

This solution allows us to create and manage Simple Electronic Signatures (SES) with a Forensic layer. With respect to a normal SES, by adding the proprietary and patented methodology that creates a forensic layer (following the standard ISO/IEC 27037:2012) WT offers a signature with a higher probatory value, positioning it between a SES and an AES. On top of that, in this signing process one can verify the identity of the signer by sending an OTP via SMS, adding more probative value.

The typical use case for this solution is a company that wants contracts to be signed electronically using a SES but needs more probative value in case of litigation, but does not want to provide an AES. The company must create this type of signatures using the endpoint [operation/createSignature] and specify the parameter isForensic = true (that is the default value) in the body, in addition to the remaining required parameters.

The following diagram shows, at a certain level of abstraction, how the signature interaction takes place once WT is integrated within the company's process.

The previous diagram not only shows the way the user and the company interact between each other once WT has been integrated, but also shows some of the WT internal processes (for transparency sake).

1. A user/signer wants to sign a document.
2. The company creates a signature using the endpoint createSignature with property isForensic = true.
3. WT initialises the signature entity that will represent the interaction during the whole process.
4. WT will return to the caller the created signature object containing the forwarding URL (F-URL) to which the company will redirect the singer.
5. The company's Web Server responds to the HTTP request sent by the user in step 1 with an HTTP Redirection to F-URL.
6. The signer’s browser visits the F-URL to WT.
7. WT will request the corresponding signature interaction for the effective URL (E-URL) where the page with the PDF will be served.
8. WT initialises a dedicated isolated secured container from which the signing environment will be served, and that will contain the tools for creating the forensic layer.
9. The E-URL is returned to WT.
10. WT will respond to the signer’s request in step 6 with an HTTP Redirection to E-URL.
11. The signer's browser visits the E-URL served from the isolated secured container where the signature will effectively take place.
12. The secured container responds with the page containing the PDF to be signed.
13. The signer will interact with the page by viewing the PDF, fill-in fields and drawing the signature (depending on the configuration), and finally will press the button that will conclude this interaction.
14. If configured, the secured container will present the signer an OTP verification page, and in parallel will send the SMS with OTP to the specified cell number.
15. The signer enters the OTP received via SMS.
16. The secured container sends the OTP to WT for validation.
17. WT validates the OTP and sends the result to the secured container.
18. The secured container will respond to the signer with an outcome page.
19. The container concludes the signing session.
20. The container updates the signature interaction with all the data needed to build the forensic layer, besides the signature specific data.
21. If configured, the outcome page may redirect the signer to a company outcome page.
22. The company will respond with its outcome page.
23. Asynchronously, WT will perform the finalisation of the interaction by applying the signatures to the PDF and by creating the Forensic Audit Trail that will accompany the signature.

This solution is fairly similar to the Document Simple Forensic API. It provides a Simple Electronic Signature (SES) with an audit trail, but in this case there won’t be an OTP identification and the audit trail is not forensic.

During the integration inside a Company’s process, to create a signature using this API, one must call the end point [operation/createSignature] although in this context using the property isForensic = false.

The following diagram shows, at a certain level of abstraction, how the signature interaction takes place once WT is integrated within the company's process.

1. A user/signer wants to sign a document.
2. The company creates a signature using the endpoint createSignature with property isForensic = false.
3. WT initialises the signature entity that will represent the interaction during the whole process.
4. WT will return to the caller the created signature object containing the forwarding URL (F-URL) to which the company will redirect the signer.
5. The company's Web Server responds to the HTTP request sent by the user in step 1 with an HTTP Redirection to F-URL.
6. The signer’s browser visits the F-URL to WT.
7. WT will request the corresponding signature interaction for the effective URL (E-URL) where the page with the PDF will be served.
8. The E-URL is returned to WT.
9. WT will respond to the signer’s request in step 6 with an HTTP Redirection to E-URL.
10. The signer's browser visits the E-URL served from the secured container where the signature will effectively take place.
11. The secured container responds with the page containing the PDF to be signed.
12. The signer will interact with the page by viewing the PDF, fill-in fields and drawing the signature (depending on the configuration), and finally will press the button that will conclude this interaction.
13. The secured container will respond to the signer with an outcome page.
14. The container concludes the signing session.
15. The container updates the signature interaction with the signature specific data.
16. If configured, the outcome page may redirect the signer to a company outcome page.
17. The company will respond with its outcome page.
18. Asynchronously, WT will perform the finalisation of the interaction by applying the signatures to the PDF and by creating the Audit Trail that will accompany the signature.

In order to create AES Signatures one must register AES providers.