Developer Pages

# Digital Evidence Management (DEM)

Page contents

# Introduction

Signicat's Digital Evidence Management platform (DEM) is a RESTful web service that allows you to securely capture, store and manage audit trail data. This can include information on authentications, payment transactions or acceptance of GDPR consent messages and enables you to efficiently handle audits and inspections. The stored data can be secured, or sealed, using Signicat's Qualified Timestamping Authority (QTSA) services.

DEM can be used for full audits of identity verification, authentication and signature processes and complies with Payment Services Directive (PSD2) (opens new window) Dynamic Linking requirements.

Data that is stored using Signicat's Digital Evidence Management platform is owned and controlled by you, as the customer, who can add, retrieve and delete transaction data and relevant metadata on demand. You determine expiry date, or Time to Live (TTL), for stored data and can search both system-provided and custom user-provided metadata in real time. Signicat acts as the data processor.

# What data is stored?

Signicat's Digital Evidence Management platform stores the following data:

  • System metadata provided by Signicat.
  • Custom metadata provided by you, as the customer.
  • A custom payload - This is the object that is protected by a timestamp.
  • A secured timestamp object - This will be used for validation of the payload.

# Supported use cases

You can define and control use cases based on your business needs. Examples of common use cases for DEM can include:

  • Payment transactions - Determine when a payment was made, what payment channel was used and if the payment triggered Strong Customer Authentication (SCA).

  • GDPR - Audit consent, information rights and the right to be forgotten.

  • Know your customer (KYC) and Anti Money Laundering (AML) - Retrieve events related to KYC and AML.

  • Fraud detection and prevention - Prevent, trace and find evidence of fraud attempts.

  • Dispute handling - Establish complaint handling mechanisms.

# Getting started

To access the DEM API, you will need a valid API client, which is a client_id/client_secret pair associated with either your organisation or with one of your accounts. The API clients are used to obtain access tokens, which are required by all DEM operations for API authorisation.

You can have multiple API clients for one account. These clients can have the following permissions, or a combination of them:

  • Write (able to store records)
  • Read (able to retrieve or search for records)
  • Update (able to update Time To Live (TTL) of records)

When you have your API client, you must obtain an access token using the OAuth 2 protocol. This is required to consume Signicat's REST services. For general information on how to do this, refer to our Quick start guide.

# API reference

In our Digital Evidence Management API reference, you can find information about the available endpoints and properties, as well as sample requests and responses.

Digital Evidence Management API
Our REST API for capturing audit trail data
REST

# Using the API

The Digital Evidence Management API is used to store audits of transactional data or consent messages. A basic process varies, but will start with the following steps:

# Step 1: Obtain an access token

Acquire an access token using the OAuth 2.0 protocol.

The following is a cURL example of a request to receive an access token:

curl --location --request POST '<ENV>/auth/open/connect/token' \
--header 'Authorization: Basic <BASE64-ENCODED CLIENTID:CLIENTSECRET>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

# Step 2: Create a new record

To create a record, make a POST call to the records endpoint. There are four required parameters: type, TTL, metadata and coreData, as well as two optional parameters: relations and auditLevel.

# Record types

Currently, the available record types are GDPR,TRANSACTION, LOG_IN, SIGNATURE and OTHER.

# Time To Live (TTL)

Specifying the Time To Live (TTL) of a record is mandatory. TTL is defined as a positive integer of 2 or higher. This value indicates the number of days until the record is deleted.

Note

A separate POST call to the records endpoint to set the expiry date for a given record is also available. This call allows you to redefine the TTL of a record in case you would like to change the expiry time of the specified record after the record has already been created.

# Metadata

The main purpose of metadata is to help in the construction of efficient search operations.

Some system metadata is automatically added to records by Signicat. System metadata includes:

  • The type of event (GDPR, transaction, etc.)
  • The time from a timestamp
  • Time To Live (TTL)

You can define custom metadata. Examples of custom metadata are:

  • Names
  • Payment amounts
  • Issuing bank account and beneficiary bank account

# Coredata

The coreData field contains the data you want to protect and timestamp.

In many cases, you will want to duplicate some of the metadata elements in the coreData payload. Other elements of the payload can be authentication information such as a JSON Web Token (JWT) (opens new window), certificates or SAML assertions. You can also include other objects such as image files. All binary data in the payload JSON structure needs to be BASE64-encoded.

# Relations

The optional relations element can contain data on relations to other records.

# Audit levels

The optional auditLevel element can contain information on which level of timestamping and verification will be applied to the record. The possible values are SIMPLE, ADVANCED and QUALIFIED.

# Request example

The following example request body shows how to create a new record.

{
    "type":"SIGNATURE",
    "TTL":2,
    "metadata":{
        "searchable_metadata": "searchable_value",
        "Jaffa_cake":"is not a biscuit",
        "number":42
    },
    "coreData": {
        "secret":"Sealed and safe"
    },
    "relations":[
        "<relation-record-uuid>"
    ]
}

Important

For the time being, the maximum record size is 10 MB.

# Other integration details

Once you have created a record, you can carry out different actions depending on use case:

  • The records endpoint allows you retrieve a list of records that match specific parameters. You can also retrieve individual records based on their ID and redefine the TTL of a record.
  • The info endpoint allows you to retrieve statistics on records in the database, such as custom metadata fields you have used.

# Searching for records

To search for a record, make a POST call to the records endpoint.

The query body consists of one or more operators (and, or). Each operator contains an array of several query objects. Each query object has 3 fields:

  • field: The metadata field the operator should be applied to. Note that system attributes are defined as system.<fieldName> and user-defined fields as custom.<fieldName>.
  • operator: The search operator (eq, ne, gt, gte, lt, lte, in, nin, contains)
  • value: The value the operator will use for the query

The available operators are:

  • eq: equal to
  • ne: not equal to
  • gt: greater than
  • gte: greater than or equal to
  • lt: less than
  • lte: less than or equal to
  • in: field value in given array (value input)
  • nin: field value not in given array (value input)
  • contains: field value matches regex (value input)

# Request example

The following example request body shows how to search for a record.

{
    "and": [
        {
            "field": "system.type",
            "operator": "eq",
            "value": "SIGNATURE"
        },
        {
            "field": "custom.numberField",
            "operator": "lt",
            "value": 42
        }
    ]
}

# Retrieving records

To retrieve a previously created record, make a GET call to the records endpoint. You can retrieve individual records based on their ID.

This GET call also validates the coreData payload to detect changes, using a secured timestamp object. You can read more about timestamping in the section on Sealing with qualified timestamps below.

Important

The ID you supply must conform to the UUID/GUID standard. Example: 123e4567-e89b-12d3-a456-556642440000. This returns everything included in the record entity.

# Sealing with qualified timestamps

Signicat can seal and secures critical data elements such as the subject and the consent that was given. This can be done by adding a qualified timestamp to these data elements using Signicat's Qualified Timestamping Authority (QTSA) services.

Timestamping data elements allows you to detect if the data has been modified and will bind the data to a proven time. The elements are then validated on retrieval.

Last updated: 11/04/2024 07:47 UTC

← API reference →