Web Acquisition (0.5.1)

Download OpenAPI specification:Download

Introduction

Welcome to the Web Acquisition (WIAS) API documentation. This API should be used to integrate WIAS into your companies' processes in order to obtain forensic prove of the fact that web interactions indeed occurred. The versioning schema of these APIs is Semver-friendly.

Overview

In a company there are certain processes that involve an interaction with an external (final user). These processes become critical when the company needs to prove that there was an interaction where the user accepted something or gave the consent for the company to do something on his behalf.

For instance, David wants to buy a SIM from a Telco, and to do so he needs to compile and submit a contract online; or John signs a contract online with a certain Internet Provider, or Jane accepts that her data can be used for shopping trend analysis by a certain Supermarket, or Mr Smith, accepts that his email can be used for advertisement by a certain DEM.

With the current technologies the company can never prove that the interaction with the user ever took place. Techniques like using the server logs as proof can be rather weak and easily rebuttable in court. On the other hand, some companies, like banks, have very strong techniques to ensure that the interaction took place. However, these techniques heavily penalize the user’s experience, hence cannot be applied in contexts where you don’t want to lose users due to complex and heavy user experiences.

The solution

What if we could seamlessly integrate inside the company's process a tool to forensically acquire a proof of an interaction between a certain user and the company?

Well, that is exactly what we will do with Web Interaction Acquisition Service (WIAS) or simply Web Acquisition. Based on the ISO standard (ISO 27037:2012) for the forensic acquisition and preservation of digital evidence, WIAS will create a forensic proof that can be used in court giving almost no space for a counterpart’s attempt to dismiss that proof.

Supported Workflows

There are currently two supported workflows.

  • The first one involves the interaction with a server-side rendered web page,
  • the second one is designed to acquire API calls, for instance when using a Single Page Application (SPA).

The later is also called Contextless interaction. The context is what the user sees when performing the interaction. For example, assume the user submits a certain form with some data. The context would be the page that the user sees, interacts with and ultimately uses to submit the form. WIAS only knows about the API call but not about the context the produced that call, hence it is Contextless.

Whereas, in the first case, WIAS is completely aware of what the users sees, as can be verified in the next section.

Server-side rendered web page

This workflow assumes that the user's interactions happen with a web page that is rendered on the server and then provided to the user.

Let's take into account the following initial scenario:


Figure 1: The original flow

Figure 1 depicts a simple user-company interaction, on which the web page at the center of the interaction is rendered server-side.

  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.

Integrating WIAS

Let's assume the company wants to forensically acquire the interaction that occurs between the user and the company's web server.

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


Figure 2: The extended flow

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

  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 WIAS API (published by its gateway). The interaction object will be composed by 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 WIAS 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 WIAS,
    • 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 section.
  3. WIAS initializes 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 WIAS gateway will return such 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 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 WIAS gateway. This endpoint does not contain the actual page.
  7. The WIAS 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 initialize a secured container to serve the effective page. The container will immediately start a forensic acquisition session.
  9. The E-URL is returned to the WIAS gateway.
  10. The WIAS gateway will respond 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 WIAS is an expansion of the normal interaction that would have taken place between the user and the company (described in Figure 1). Note that those are steps 1, 12, 17 and 18 of the previous flow.

Contextless interaction

This workflow defines how to use WIAS 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. It will not include any context whatsoever (i.e. the SPA itself). Let's take into account the following initial scenario:


Figure 3: The original flow

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

  1. The user opens a company's URL, wherefrom 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 WIAS'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.

Integrating WIAS

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

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


Figure 4: The extended flow

In **Figure 4** there is no reference to the fact that the user opened and interacted with the SPA. Since those actions are out of WIAS' scope we will start from the moment the API call was 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 WIAS;

    Note: at this point, the company must prevent the user to do the action that triggers the request the company wants to acquire with WIAS.

  2. The company's Web Server, instead of responding right away, will create a new interaction using the WIAS API (published by its gateway). In that case, since there is no context, the interaction will be composed of the URL where the company intends to handle the user's action (O-URL) and no_html as the parameter variation;

    The user's Request that the company wants to acquire with WIAS has to be sent to WIAS 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, WIAS can redirect the request to this Url.

  3. WIAS initializes 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 WIAS gateway will return such 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 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 WIAS 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 WIAS gateway.

  7. At that point the WIAS gateway asks the corresponding interaction for the effective URL (E-URL). This Url will be an endpoint within WIAS, to where the action will be redirected in order to perform a forensic acquisition.

  8. The previous action will indicate our system to initialize 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 WIAS gateway.

  10. The WIAS gateway will respond 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 WIAS is an expansion of the normal interaction that would have taken place between the user and the company (described in Figure 3). Note that those are steps 1 and 16 of the previous flow.

Authentication

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

Impersonators

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 WIAS 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.

http_basic_schema

Using the http basic authentication scheme, the user authenticates to WIAS specifying a provided credential string inside the Authorization header. This credential string is a base64 encoding of id:secret.

  Authorization: Basic <base64-credential-string>

Note that using curl or one of our clients you don't have to transform to base64 by yourself. It is enough to specify id:secret.

Security scheme type: HTTP
HTTP Authorization Scheme basic

archetypes

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.

Create an archetype

This API call allows you to create an archetype.

Authorizations:
header Parameters
Authorization
required
string
Example: "Basic <base64-credential-string>"
Accept
required
application/json
Content-Type
required
application/json
Request Body schema: application/json
mandatoryTags
object

An object representing the tags to be added to the Interaction. Note: tag names can only contain US-ASCII letters and/or numbers. You can specify as many tag names as you like. In future you will be able to specify a regular expression to validate the tag value as well. For now, only null is accepted as value.

name
string

Archetype's given name

Responses

200

The archetype was created.

401

Unauthorized -- the specified credentials are wrong.

500

Internal Server Error.

post /archetypes

Production server

https://api.websign.kopjra.com/v1/archetypes

Demo server

https://api-demo.websign.kopjra.com/v1/archetypes

Request samples

application/json
Copy
Expand all Collapse all
{
  • "mandatoryTags":
    {
    },
  • "name": "Archetype 1"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 6,
  • "name": "Archetype 1",
  • "mandatoryTags":
    {
    },
  • "updatedAt": "2018-07-04T14:30:24.931Z",
  • "createdAt": "2018-07-04T14:30:24.931Z"
}

Get all archetypes

You can use this endpoint to get all of your Archetypes.

Authorizations:
query Parameters
top
integer [ 1 .. 25 ]
Default: 5

The maximum number of object to be returned.

skip
integer >= 0
Default: 0

The number of results to be skipped starting from the first result. Used for pagination.

sortBy
string
Example: "name,-createdAt"

A sorting criteria. It must be specified as comma separated list of terms, where each term can be: prop or +prop or -prop. The operator + or the absence of it indicates an ascending sorting direction, whereas the - operator indicates a descending sorting direction. prop can be one of the following:

  • id
  • name
  • createdAt
  • updatedAt

For example a valid sorting criteria specification would be:

sortBy=name,-createdAt

With this criteria you will get a list of interaction sorted by name and for each equal name then it will be sorted by createdAt in descending order.

Responses

200

The requested archetypes could be retrieved

401

Unauthorized -- the specified credentials are wrong.

500

Internal Server Error.

get /archetypes

Production server

https://api.websign.kopjra.com/v1/archetypes

Demo server

https://api-demo.websign.kopjra.com/v1/archetypes

Request samples

Copy
curl "{SERVER}/archetypes"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

# TODO: Replace id:secret with the proper credentials

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get an archetype by Id

This endpoint retrieves a specific archetype.

Authorizations:
path Parameters
archetypeId
required
number
Example: 85
header Parameters
Authorization
required
string
Example: "Basic <base64-credential-string>"
Accept
required
application/json

Responses

200

The requested archetype could be retrieved

401

Unauthorized -- the specified credentials are wrong.

404

Not Found -- The specified resource could not be found.

500

Internal Server Error.

get /archetypes/{archetypeId}

Production server

https://api.websign.kopjra.com/v1/archetypes/{archetypeId}

Demo server

https://api-demo.websign.kopjra.com/v1/archetypes/{archetypeId}

Request samples

Copy
curl "{SERVER}/archetypes/85"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -H "Authorization: Basic id:secret"

// TODO: Replace id:secret with the proper credentials

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 1,
  • "name": "Archetype 1",
  • "createdAt": "2019-04-19T18:33:43Z",
  • "updatedAt": "2019-04-19T18:33:43Z",
  • "mandatoryTags":
    {
    }
}

interactions

An interaction represents the minimum entity that can be forensically acquired, stored and retrieved. It represents a specific action done by the user, plus the context of that action (i.e. the web page that the users sees)

Create an interaction

Before you can acquire an action done by one of the users (and its context), you need to create a new interaction, and redirect the user to the forward URL (fUrl) specifically provided by WIAS. You will find this fUrl inside the body of the response of this call.

At the end of this call, remember to redirect your user to fUrl!

Since we don't implement any of your backend business logic, the user's request needs eventually to be re-submitted to your web server. Therefore you must provide us with the oURL where the endpoint that receives the user request must reside.

This call supports two different variations: full or no_html. The first one corresponds to the case of Server Side Rendered Web Application Full Interaction and the second one corresponds to the case of Context-less Interaction.

If you use the full variation, you need to provide us with some HTML that will be the context on which the user is going to do his action. The user's action could be for instance a form submission (a POST or a GET) or the click on a link (only a GET). In both cases, you have to pre-render the HTML on your server and give it to us.

Within your pre-rendered HTML, remember to replace the URL where you originally intended to handle the user's action with the <%= e_url %> placeholder.

Otherwise, if you use the no_html variation, WIAS will just acquire the single action coming from the user to your service (MITM'ed by WIAS) with no information about its context. In this case, you will not have to provide us any pre-rendered HTML.

Moreover, it is possible to specify a Callback URL where WIAS will send a POST request at the end of the single interaction process, stating if everything went OK (in this case, the body of the POST request will include the body sent from the user to our system) or if an error occurred. Currently WIAS ignores this parameter: feature still to be implemented.

Finally, you can also decide to put any tag on your interaction.

Future retrievals requests can only be done by matching interaction IDs or custom tags! Otherwise, we won't be able to fetch the data contained in your pre-rendered HTML or in the content submitted by your user's action.

Authorizations:
header Parameters
Authorization
required
string
Example: "Basic <base64-credential-string>"
Accept
required
application/json
Content-Type
required
application/json
Request Body schema: application/json

Interaction creation object

oURL
required
string

Original URL. The URL where the request was originally intended to go. At the end of the acquisition process, the user will automatically re-submit the request to this URL. The company's service must be ready to serve the user's request in this URL.

callbackUrl
string
Deprecated

Ignored by the system. Deprecated in v0.5.0, it will be removed in v1.0.0.

variation
string
Default: "full"
Enum:"full" "no_html"

The variation you want to use, depending on whether the interaction is intended for server-side rendered web pages or api call. Therefore indicates if the interaction will have context or not.

prerenderedHtml
string

The pre-prendered HTML to be displayed by WIAS's container web server. It must contain the string <%= e_url %> somewhere in it. It is mandatory if the variation is undefined or full.

archetypeId
integer >= 1

If the interation has an archetype, this field represents the archetypes's unique identifier.

tags
object

An object representing the tags to be added to the Interaction. Note: tag names can only contain US-ASCII letters and/or numbers, whereas tag values can be any UTF-8 string.

Responses

201

The interaction creation was issued and its being proccessed.

400

The specified payload is not correct

401

Unauthorized -- the specified credentials are wrong.

500

Internal Server Error.

post /interactions

Production server

https://api.websign.kopjra.com/v1/interactions

Demo server

https://api-demo.websign.kopjra.com/v1/interactions

Request samples

application/json
Copy
Expand all Collapse all
{}

Get all interactions

You can use this endpoint to get all of your Interactions. In the future, you will also be able to search among interactions using custom tags (still to be implemented).

This endpoint retrieves all of your interactions. Please note that the attached files are not shown here: they are shown on a single-interaction basis.

Authorizations:
query Parameters
top
integer [ 1 .. 25 ]
Default: