NAV Navbar
shell

Introduction

Welcome to Datatrust documentation!

Datatrust by Blockchain Partner allows you to sign and certify all your documents on the Ethereum blockchain in the blink of an eye! It makes it easy to handle loads of documents and to share trusted certificates with your clients.

You can see code examples in the area to the right.

Our API follows OpenAPI specifications. Have a look at it and test your requests online !

Roles and Authentication

Most endpoints of Datatrust API require authentication. Those which do not are clearly specified as such in this documentation.

A system of roles, built upon two types of users (administrators and simple users), gives you precise control over users' permissions.

Datatrust API moreover supports two methods of authentication: JSON Web Tokens and Basic Authentication.

Roles

accounts, users and documents

As shown in the figure above, each user can certify documents in the name of the main account, has its own credentials and is either an administrator or a simple user, giving him/her different permissions as specified in the following table.

Administrator (admin) Simple user (subuser)
Get account features
Create a new user
Get own user features
Manage JSON Web Tokens
Edit and delete own features
Get other users' features
Edit and delete other users' features
Certify and manage documents
Upload and download source documents
Download PDF certificates

JSON Web Tokens

JSON Web Tokens are the preferred solution to authenticate your requests. A very flexible and practicle manager, explained in a dedicated section, let you create numerous JWTs and attach descriptions to easily filter them out.

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.datatrust.fr/<api_endpoint>" \
    -H "Authorization: Bearer my_jwt_here"

Make sure to replace my_jwt_here with your API key.

Datatrust API expects for a valid JWT to be included in a standard header:

Bearer my_jwt_here

Basic Authentication

You can also use Basic Authentication:

curl "https://api.datatrust.fr/<api_endpoint>" \
    -u "my_email:my_password"

Make sure to replace my_email and my_password with your credentials.

You can use Basic Authentication, with standard template:

my_email:my_password

Request Parameters

Request parameters should be submitted as JSON objects.

Errors

Datatrust API makes use of the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your credentials are wrong.
405 Method Not Allowed -- You try to use an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Account

As tackled above, when you subscribe to Datatrust, an Account object is created for you. You can then create User objects which all belong to this account. They each have their own credentials and features, but all share the same account default features.

Get Account Features

To get your account features, use this code:

curl "https://api.datatrust.fr/account" \
    -H "Authorization: Bearer my_jwt_here"

The above command returns JSON structured like this:

{
    "anchoringSchedule": [false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false, false],
    "defaults": {
        "docDiscoverableByDefault": false,
        "documentsTags": {
            "tag0": 2
        },
        "documentsTypes": {
            "image/png": 3
        },
        "language": "en",
        "largestDocumentSize": 0,
        "signatureServerEnabled": true,
        "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
        "signatureServerEthKeyId": 0,
        "webhookEnabled": false,
        "webhook": ""
    },
    "flashAnchoringOption": false,
    "logoUrl": "https://mycompany.co/logo.svg",
    "userManualUrl": "https://mycompany.co/user-manual.pdf",
    "verificationPageUrl": "https://mycompany.co/verify",
    "showOwnerOnPdfCertificate": true,
    "mainPrimaryColor": "#1f9e5b",
    "mainSecondaryColor": "#eaa522",
    "maxNbUsers": 20,
    "maxNbAnchorsEnabled": true,
    "maxNbAnchors": 100000,
    "name": "mycompany",
    "sourceStorageOption": false,
    "sourceStorageSpace": 0,
    "sourceStorageUsedSpace": 0,
    "tokens": [
        {
            "expirationDate": "Sat, 30 Jun 2018 14:39:25 GMT",
            "description": "Alice - June 2018",
            "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzAzNjk1NjUsImlhdCI6MTUyOTkxODU5Nn0.t6PgMdNddWMGVpNp0j0mmN2r7cajObccNpIE0hUCxvY"
        }
    ]
}

This endpoint retrieves all your account features.

HTTP Request

GET https://api.datatrust.fr/account

Query Results

Feature Type Description
anchoringSchedule boolean[24] Schedule of daily anchoring. If anchoringSchedule[10] is true then an anchoring session will occure everyday at 10:00:00 GMT.
defaults object Account default values, detailled below.
flashAnchoringOption boolean Status of the flash anchoring option. If this and the user-level option are active, documents will instantly be certified once submitted.
logoUrl string Logo URL.
userManualUrl string URL of a custom user manual.
verificationPageUrl string Custom URL of the webapp to use for the verification of certificates validity.
showOwnerOnPdfCertificate boolean Option allowing to show or hide the account name from PDF certificates.
mainPrimaryColor string Hex primary color.
mainSecondaryColor string Hex secondary color.
maxNbUsers integer Maximum number of users.
maxNbAnchorsEnabled boolean Status of the limitation on the number of anchors per month at the account level. If true, then your maximum number of certifications per month will be limited to maxNbAnchors.
maxNbAnchors integer Maximum number of allowed certifications per month in case this limitation is enabled at the account level.
name string Name of the account.
sourceStorageOption boolean Status of the source storage option. When activated, you can use rely on Datatrust to store the documents you certify.
sourceStorageSpace integer Maximum online storage space for your source documents (in bytes).
sourceStorageUsedSpace integer Currently used online storage space (in bytes).

The defaults object holds various subsidiary features detailled below.

Feature Type Description
docDiscoverableByDefault boolean Set the docDiscoverableByDefault feature for new users.
documentsTags object Mapping from your document tags to their number of occurrence.
documentsTypes object Mapping from your document MIME types to their number of occurrence.
language string Set the language feature for new users.
largestDocumentSize integer Size of the largest anchored document (in bytes).
signatureServerEnabled boolean Set the status of the document signature webservice for new users.
signatureServerURI string Set the URI of your secure signature webservice for new users.
signatureServerEthKeyId integer Set the ID of the signing key to use for new users.
webhookEnabled boolean Set the status of the webhook service for new users.
webhook string Set the default webhook URI for new users.

Anchoring limits

The number of files you anchor may be limited per month. Should you reach that threshold, you may contact Blockchain Partner to raise that limit.

To find the number of files remaining for the month, use this code:

curl "https://api.datatrust.fr/account/remaining-nb-anchors" \
    -X GET
    -H "Authorization: Bearer my_jwt_here"

The above command returns JSON structured like this:

{
  "accountMaxNbAnchorsEnabled": true,
  "accountMaxNbAnchors": 100000,
  "accountRemainingNbAnchors": 40000,
  "userMaxNbAnchorsEnabled": true,
  "userMaxNbAnchors": 2000,
  "userRemainingNbAnchors": 1000
}

User

Create New User

To create a new user, use this code:

curl https://api.datatrust.fr/user \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "user": {
            "features": {
                "email": "alice@mycompany.co",
                "name": "alice",
                "company": "mycompany",
                "flashAnchoringOption": true,
                "maxNbAnchorsEnabled": false,
                "maxNbAnchors": 0
            },
            "roles": [
                "subuser"
            ],
            "defaults": {
                "docDiscoverableByDefault": false,
                "language": "en",
                "signatureServerEnabled": true,
                "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
                "signatureServerEthKeyId": 0,
                "webhookEnabled": true,
                "webhook": "https://personal.webhook.co"
            }
        }
    }'

The above command returns the new user JSON object structured like this:

{
    "features": {
        "email": "alice@mycompany.co",
        "name": "alice",
        "company": "mycompany",
        "flashAnchoringOption": true,
        "maxNbAnchorsEnabled": false,
        "maxNbAnchors": 0
    },
    "roles": [
        "subuser"
    ],
    "defaults": {
        "docDiscoverableByDefault": false,
        "language": "en",
        "signatureServerEnabled": true,
        "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
        "signatureServerEthKeyId": 0,
    "webhookEnabled": true,
    "webhook": "https://personal.webhook.co"
    }
}

This endpoint creates a new user.

HTTP Request

POST https://api.datatrust.fr/user

Query Parameters

Parameter Type Optional Description
email string A valid email address used for identity verification.
name string A user name.
company string An optional company name.
flashAnchoringOption boolean User-level status of the flash anchoring option.,
maxNbAnchorsEnabled boolean Status of the limitation on the number of anchors per month at the user level. If true, then your maximum number of certifications per month will be limited to maxNbAnchors.
maxNbAnchors integer Maximum number of allowed certifications per month in case this limitation is enabled at the user level.
roles string[] List of role names, such as admin or subuser.
docDiscoverableByDefault boolean If true, any new document will be set as discoverable by default once submitted.
language string Language Code Identifier.
signatureServerEnabled boolean Status of the document signature webservice.
signatureServerURI string URI of your secure signature webservice.
signatureServerEthKeyId integer ID of the signing key in case you are willing to handle more than one.
webhookEnabled boolean Default status of the webhook feature for new documents.
webhook string Default webhook URI to be used on new documents certification.

Get User Features

To get your user features, use this code:

curl "https://api.datatrust.fr/user/<username>" \
    -H "Authorization: Bearer my_jwt_here"

The above command returns the new user JSON object structured like this:

{
    "features": {
        "email": "alice@mycompany.co",
        "name": "alice",
        "company": "mycompany",
        "flashAnchoringOption": true,
        "maxNbAnchorsEnabled": false,
        "maxNbAnchors": 0
    },
    "roles": [
        "subuser"
    ],
    "defaults": {
        "docDiscoverableByDefault": false,
        "language": "en"
    }
}

This endpoint retrieves all your basic user features.

HTTP Request

GET https://api.datatrust.fr/user/<username>

Filter Users

To filter users, use this code:

curl "https://api.datatrust.fr/user/search" \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "options": {
            "filter": {
                "features": {
                    "name": "alice"
                }
            },
            "excludedFields": [
                "defaults"
            ],
            "sortBy": [
                "-features.name"
            ],
            "skip": 0,
            "limit": 10
        }
    }'

The above command returns JSON structured like this:

[
    {
        "features": {
            "email": "alice@mycompany.co",
            "name": "alice",
            "company": "mycompany",
            "flashAnchoringOption": true,
            "maxNbAnchorsEnabled": false,
            "maxNbAnchors": 0
        },
        "roles": [
            "subuser"
        ]
    }
]

If you are only interested in the number of documents matching a filter, you can just change the URI to https://api.datatrust.fr/user/search/count.

It would return the following:

{
    "count": 1
}

This endpoint filters your personal documents.

Get All Users' Features

To get a list of all users' features, use this code:

curl "https://api.datatrust.fr/users" \
    -H "Authorization: Bearer my_jwt_here"

The above command returns different objects depending on your roles. If you have administration rights, the JSON object would be structured like this:

[
    {
        "features": {
            "email": "alice@mycompany.co",
            "name": "alice",
            "company": "mycompany",
            "flashAnchoringOption": true,
            "maxNbAnchorsEnabled": false,
            "maxNbAnchors": 0
        },
        "roles": [
            "subuser"
        ],
        "defaults": {
            "docDiscoverableByDefault": false,
            "language": "en",
            "signatureServerEnabled": true,
            "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
            "signatureServerEthKeyId": 0,
            "webhookEnabled": true,
            "webhook": "https://personal.webhook.co"
        }
    }
]

This endpoint retrieves a list of all user's features.

HTTP Request

GET https://api.datatrust.fr/users

Edit User Features

To edit your user features, use this code:

curl https://api.datatrust.fr/user/<username> \
    -X PUT \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "user": {
            "features": {
                "email": "alice@mycompany.co",
                "name": "alice",
                "company": "mycompany",
                "flashAnchoringOption": true,
                "maxNbAnchorsEnabled": false,
                "maxNbAnchors": 0
            },
            "roles": [
                "subuser"
            ],
            "defaults": {
                "docDiscoverableByDefault": false,
                "language": "en",
                "signatureServerEnabled": true,
                "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
                "signatureServerEthKeyId": 0,
                "webhookEnabled": true,
                "webhook": "https://personal.webhook.co"
            }
        },
        "password": "DO_NOT_USE_THIS_PASSWORD"
    }'

Use this endpoint to edit your user features.

HTTP Request

PUT https://api.datatrust.fr/user/<username>

Query Parameters

Parameter Type Optional Description
email string A valid email address used for identity verification.
name string A user name.
company string An optional company name.
flashAnchoringOption boolean User-level status of the flash anchoring option.,
maxNbAnchorsEnabled boolean Status of the limitation on the number of anchors per month at the user level. If true, then your maximum number of certifications per month will be limited to maxNbAnchors.
maxNbAnchors integer Maximum number of allowed certifications per month in case this limitation is enabled at the user level.
roles string[] List of role names, such as admin or subuser.
docDiscoverableByDefault boolean If true, any new document will be set as discoverable by default once submitted.
language string Language Code Identifier.
signatureServerEnabled boolean Status of the document signature webservice.
signatureServerURI string URI of your secure signature webservice.
signatureServerEthKeyId integer ID of the signing key in case you are willing to handle more than one.
webhookEnabled boolean Default status of the webhook feature for new documents.
webhook string Default webhook URI to be used on new documents certification.
password string A new secure enough password.,

Delete User

To delete a user, use this code:

# THIS COMMAND WILL DELETE YOUR USER ACCOUNT !!
# IT CANNOT BE UNDONE !!
curl "https://api.datatrust.fr/user/<username>" \
    -X DELETE \
    -H "Authorization: Bearer my_jwt_here"
# THIS COMMAND WILL DELETE YOUR USER ACCOUNT !!
# IT CANNOT BE UNDONE !!

This endpoint deletes your user account.

HTTP Request

DELETE https://api.datatrust.fr/user/<username>

JSON WEB Token

JSON Web Tokens are the preferred solution to authenticate your requests.

Each JWT is proper to a user and attached to it is a textual description to help you manage your set of JWTs.

Create New JWT

To create a new JWT, use this code:

curl https://api.datatrust.fr/token \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "expirationTime": "2018-06-30 14:39:25",
        "description": "Alice - June 2018"
    }'

The above command returns a JSON object structured like this:

{
    "expirationDate": "Sat, 30 Jun 2018 14:39:25 GMT",
    "description": "Alice - June 2018",
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzAzNjk1NjUsImlhdCI6MTUyOTkxODU5Nn0.t6PgMdNddWMGVpNp0j0mmN2r7cajObccNpIE0hUCxvY"
}

This endpoint creates a new JWT.

HTTP Request

POST https://api.datatrust.fr/token

Query Parameters

Parameter Type Description
expirationTime string | integer Expiration date of your token. Any date in the future will be accepted as long as it is parseable by dateutil parser.
description string Description of your JWT usage.

Query Results

Feature Type Description
expirationTime string Expiration date of the token.
description string Description of the JWT usage.
jwt string JSON Web Token you can use to authenticate requests.

Get JWT

To get details about a JWT, use this code:

curl "https://api.datatrust.fr/token/<string:jwt>" \
    -H "Authorization: Bearer my_jwt_here"

The above command returns a JSON object structured like this:

{
    "expirationDate": "Sat, 30 Jun 2018 14:39:25 GMT",
    "description": "Alice - June 2018",
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzAzNjk1NjUsImlhdCI6MTUyOTkxODU5Nn0.t6PgMdNddWMGVpNp0j0mmN2r7cajObccNpIE0hUCxvY"
}

This endpoint retrieves details about a JWT.

HTTP Request

GET https://api.datatrust.fr/token/<string:jwt>

Query Results

Feature Type Description
expirationTime string Expiration date of your token.
description string Description of the JWT usage.
jwt string JSON Web Token you can use to authenticate requests.

Get All JWTs

To get a list of all JWTs attached to your account, use this code:

curl "https://api.datatrust.fr/tokens" \
    -H "Authorization: Bearer my_jwt_here"

The above command returns a JSON array structured like this:

[
    {
        "expirationDate": "Sat, 30 Jun 2018 14:39:25 GMT",
        "description": "Alice - June 2018",
        "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzAzNjk1NjUsImlhdCI6MTUyOTkxODU5Nn0.t6PgMdNddWMGVpNp0j0mmN2r7cajObccNpIE0hUCxvY"
    }
]

This endpoint retrieves a list of all JWTs attached to your account.

HTTP Request

Query Results

Feature Type Description
expirationTime string Expiration date of your token.
description string Description of the JWT usage.
jwt string JSON Web Token you can use to authenticate requests.

Edit JWT

To edit details of a JWT, use this code:

curl "https://api.datatrust.fr/token/<string:jwt>" \
    -X PUT \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "token": {
            "description": "Bob - June 2018"
        }
    }'

The above command returns a JSON object structured like this:

{
    "expirationDate": "Sat, 30 Jun 2018 14:39:25 GMT",
    "description": "Bob - June 2018",
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MzAzNjk1NjUsImlhdCI6MTUyOTkxODU5Nn0.t6PgMdNddWMGVpNp0j0mmN2r7cajObccNpIE0hUCxvY"
}

This endpoint let you edit details of a JWT.

HTTP Request

GET https://api.datatrust.fr/token/<string:jwt>

Query Results

Feature Type Description
expirationTime string Expiration date of your token.
description string Description of the JWT usage.
jwt string JSON Web Token you can use to authenticate requests.

Delete JWT

To get details about a JWT, use this code:

curl "https://api.datatrust.fr/token/<string:jwt>" \
    -X DELETE `
    -H "Authorization: Bearer my_jwt_here"

This endpoint retrieves details about a JWT.

HTTP Request

GET https://api.datatrust.fr/token/<string:jwt>

Documents

Create New Document

To create a new document, use this code:

curl "https://api.datatrust.fr/document/<string:digest>" \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "features": {
            "name": "My document name",
            "description": "My document description",
            "type": "image/jpeg",
            "tags": [
                "tag#0",
                "tag#1"
            ],
            "size": 241867,
            "discoverable": true,
            "archived": false,
            "webhook": "https://personal.webhook.co"
        }
    }'

The above command returns JSON structured like this:

{
    "anchor": {
        "standardProof": {},
        "status": "PENDING"
    },
    "creator": {
            "email": "alice@mycompany.co",
            "name": "alice"
    },
    "features": {
        "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
        "name": "My document name",
        "description": "My document description",
        "type": "image/jpeg",
        "tags": [
            "tag#0",
            "tag#1"
        ],
        "size": 241867,
        "creationTimestamp": "Sat, 30 Jun 2018 14:39:25 GMT",
        "discoverable": true,
        "archived": false,
        "webhook": "https://personal.webhook.co",
        "storedOnline": false
    },
    "signatures": [],
    "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93"
}

Once the anchoring is effectively sent to the Ethereum network, the anchor status is temporarily changed to WAITING_TO_BE_MINED. Shortly after, the anchor field is populated with its final body, structured like:

{
    "anchor": {
        "standardProof": {
            "@context": "https://w3id.org/chainpoint/v2",
            "anchors": [
                {
                    "type": "ETHData",
                    "sourceId": "7fe3954d822594963df26ab3ea4c8c3d435bac9c4c133dd57968b6f7fbf70168"
                }
            ],
            "merkleRoot": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
            "proof": [ ],
            "targetHash": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
            "type": "ChainpointSHA256v2"
        },
        "status": "VALID",
        "timestamp": "Sat, 30 Jun 2018 15:00:05 GMT",
    },
    "creator": {},
    "features": {},
    "signatures": [],
    "publicId": 
}

This endpoint registers a new document. The status of such a document is set to PENDING until the stack of pending documents is saved.

If you subscribed to Data Flash, your document will be instantly certified.

HTTP Request

POST https://api.datatrust.fr/document/<string:digest>

Query Parameters

Parameter Type Optional Default Description
digest 64-hex-char string SHA256 hexadecimal digest of the document.
name string Name of the document.
description string Description of the document.
type string Type of document.
tags array of strings List of tags attached to the document.
size integer Size in bytes of the document.
discoverable boolean false If true, the certification receipt will not be required to verify the document.
archived boolean false Archived status, used to hide documents from the web interface for instance.
webhook string Webhook to be called once actual certification has been triggered. See dedicated section for more information.

Query Results

Feature Description
anchor Details related to the certification process.
creator Public features of the user who certified this document.
features Private features associated to the document.
signatures List of cryptographic signatures attached to the document and certified on the blockchain.
publicId A unique ID of the document. If the discoverable feature of the document is set to true, you can share its public ID to enable anyone to download the related certificate.

Get Specific Document

To get a specific personal document, use this code:

curl "https://api.datatrust.fr/document/<string:digest>" \
    -H "Authorization: Bearer my_jwt_here"

The above command returns JSON structured like this:

{
    "anchor": {
        "standardProof": {},
        "status": "PENDING"
    },
    "creator": {
            "email": "alice@mycompany.co",
            "name": "alice"
    },
    "features": {
        "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
        "name": "My document name",
        "description": "My document description",
        "type": "image/jpeg",
        "tags": [
            "tag#0",
            "tag#1"
        ],
        "size": 241867,
        "creationTimestamp": "Sat, 30 Jun 2018 14:39:25 GMT",
        "discoverable": true,
        "archived": false,
        "webhook": "https://personal.webhook.co",
        "storedOnline": false
    },
    "signatures": [],
    "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93"
}

This endpoint retrieves a specific personal document identified by its SHA256 digest.

HTTP Request

GET https://api.datatrust.fr/document/<string:digest>

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of a document.

Query Results

Feature Description
anchor Details related to the certification process.
creator Public features of the user who certified this document.
features Private features associated to the document.
signatures List of cryptographic signatures attached to the document and certified on the blockchain.
publicId A unique ID of the document. If the discoverable feature of the document is set to true, you can share its public ID to enable anyone to download the related certificate.

Get Specific Public Document

To get a specific public document, use this code:

curl "https://api.datatrust.fr/document/public/<string:digest>"

The above command returns JSON structured like this:

[
    {
        "accountName": "mycompany",
        "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93",
        "stdProof": {
            "@context": "https://w3id.org/chainpoint/v2",
            "type": "ChainpointSHA256v2",
            "anchors": [
                {
                    "sourceId": "37137e6d5334501ac6c01c4984cd5552e817f46e832ba0bf6a6375886b174cbe",
                    "type": "ETHData"
                }
            ],
            "merkleRoot": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
            "targetHash": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
            "proof": []
        },
        "timestamp": "Sat, 30 Jun 2018 17:00:25 GMT"
    }
]

A document can be saved by multiple users. If one of them chooses to make its proof public, anyone who owns the original document can verify that the document was already saved by this user.

With this endpoint, you can retrieve for a specific document identified by its SHA256 digest, the list of users who previously saved this document and disclosed it.

HTTP Request

GET https://api.datatrust.fr/document/public/<string:digest>

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of a document.

Query Results

The command returns a JSON array containing documents with the following features.

Feature Description
accountName Name of the owner's account.
publicId A unique ID of the document. If the discoverable feature of the document is set to true, you can share its public ID to enable anyone to download the related certificate.
stdProof Chainpoint v2 standard proof.
timestamp Time of certication.

Filter Documents

To filter your personal documents, use this code:

curl "https://api.datatrust.fr/document/search" \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "options": {
            "filter": {
                "anchor": {
                    "status": {
                        "$ne": "PENDING"
                    }
                }
            },
            "searchText": "",
            "excludedFields": [
                "anchor.standardProof"
            ],
            "from": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
            "to": "",
            "inclusive": true,
            "sortBy": [
                "-features.creationTimestamp"
            ],
            "skip": 0,
            "limit": 10
        }
    }'

The above command returns JSON structured like this:

[
    {
        "anchor": {
            "standardProof": {},
            "status": "PENDING"
        },
        "creator": {
                "email": "alice@mycompany.co",
                "name": "alice"
        },
        "features": {
            "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
            "name": "My document name",
            "description": "My document description",
            "type": "image/jpeg",
            "tags": [
                "tag#0",
                "tag#1"
            ],
            "size": 241867,
            "creationTimestamp": "Sat, 30 Jun 2018 14:39:25 GMT",
            "discoverable": true,
            "archived": false,
            "webhook": "https://personal.webhook.co",
            "storedOnline": false
        },
        "signatures": [],
        "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93"
    }
]

If you are only interested in the number of documents matching a filter, you can just change the URI to https://api.datatrust.fr/document/search/count.

It would return the following:

{
    "count": 1
}

You may also batch several requests of this type into one using the following endpoints : https://api.datatrust.fr/document/search/batch and https://api.datatrust.fr/document/search/count/batch.

Just use the batch feature in your request body:

curl "https://api.datatrust.fr/document/search/batch" \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "batch": [
            "options": {
                "filter": {
                    "anchor": {
                        "status": {
                            "$ne": "PENDING"
                        }
                    }
                },
                "searchText": "",
                "excludedFields": [
                    "anchor.standardProof"
                ],
                "from": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
                "to": "",
                "inclusive": true,
                "sortBy": [
                    "-features.creationTimestamp"
                ],
                "skip": 0,
                "limit": 10
            }
        ]
    }'

It would return the following:

[
    [
        {
            "anchor": {
                "standardProof": {},
                "status": "PENDING"
            },
            "creator": {
                    "email": "alice@mycompany.co",
                    "name": "alice"
            },
            "features": {
                "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
                "name": "My document name",
                "description": "My document description",
                "type": "image/jpeg",
                "tags": [
                    "tag#0",
                    "tag#1"
                ],
                "size": 241867,
                "creationTimestamp": "Sat, 30 Jun 2018 14:39:25 GMT",
                "discoverable": true,
                "archived": false,
                "webhook": "https://personal.webhook.co",
                "storedOnline": false
            },
            "signatures": [],
            "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93"
        }
    ]
]

The result of the related batched count request would look like:

[
    {
        "count": 1
    }
]

This endpoint filters your personal documents.

HTTP Request

POST https://api.datatrust.fr/document/search

POST https://api.datatrust.fr/document/search/batch

POST https://api.datatrust.fr/document/search/count

POST https://api.datatrust.fr/document/search/count/batch

Query Parameters

Parameter Type Optional Default Description
filter JSON object {} Mongo-like filter on the documents to retrieve. For instance: { "stamp": { "status": "PENDING" }}.
excludedFields array of strings [] Array of Mongo-formatted features to be excluded from the result.
searchText string Textual search query.
from 64-hex-char string SHA256 hexadecimal digest of the latest document to retrieve.
to 64-hex-char string SHA256 hexadecimal digest of the oldest document to retrieve.
inclusive boolean true True if documents matching from and to parameters should be included.
sortBy array of strings false Mongo-like sorting keys. The order may be specified by prepending each of the keys by a + or a -. Ascending order is assumed.
skip integer 0 Number of documents to skip.
limit integer Limit to the number of documents to retrieve.

Query Results

A POST https://api.datatrust.fr/document/search command returns a JSON array containing documents with the following features.

Feature Description
anchor Details related to the certification process.
creator Public features of the user who certified this document.
features Private features associated to the document.
signatures List of cryptographic signatures attached to the document and certified on the blockchain.
publicId A unique ID of the document. If the discoverable feature of the document is set to true, you can share its public ID to enable anyone to download the related certificate.

With the URI https://api.datatrust.fr/document/search/count, only the number of documents matching the filter is returned.

Feature Description
count Number of documents matching the filter.

Edit Document Features

To edit a personal document features, use this code:

curl "https://api.datatrust.fr/document/<string:digest>" \
    -X PUT \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "features": {
            "name": "My document name",
            "description": "My document description",
            "type": "image/jpeg",
            "tags": [
                "tag#0",
                "tag#1"
            ],
            "size": 241867,
            "discoverable": true,
            "archived": false,
            "webhook": "https://personal.webhook.co"
        }
    }'

The above command returns JSON structured like this:

{
    "anchor": {
        "standardProof": {},
        "status": "PENDING"
    },
    "creator": {
            "email": "alice@mycompany.co",
            "name": "alice"
    },
    "features": {
        "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
        "name": "My document name",
        "description": "My document description",
        "type": "image/jpeg",
        "tags": [
            "tag#0",
            "tag#1"
        ],
        "size": 241867,
        "creationTimestamp": "Sat, 30 Jun 2018 14:39:25 GMT",
        "discoverable": true,
        "archived": false,
        "webhook": "https://personal.webhook.co",
        "storedOnline": false
    },
    "signatures": [],
    "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93"
}

Use this endpoint to edit your personal document details.

HTTP Request

PUT https://api.datatrust.fr/document/<string:digest>

Query Parameters

Parameter Type Optional Default Description
digest 64-hex-char string SHA256 hexadecimal digest of the document.
name string Name of the document.
description string Description of the document.
type string Type of document.
tags array of strings List of tags attached to the document.
size integer Size in bytes of the document.
discoverable boolean false If true, the certification receipt will not be required to verify the document.
archived boolean false Archived status, used to hide documents from the web interface for instance.
webhook string Webhook to be called once actual certification has been triggered. See dedicated section for more information.

Query Results

Feature Description
anchor Details related to the certification process.
creator Public features of the user who certified this document.
features Private features associated to the document.
signatures List of cryptographic signatures attached to the document and certified on the blockchain.
publicId A unique ID of the document. If the discoverable feature of the document is set to true, you can share its public ID to enable anyone to download the related certificate.

Delete Document

To delete a personal document, use this code:

curl "https://api.datatrust.fr/document/<string:digest>" \
    -X DELETE \
    -H "Authorization: Bearer my_jwt_here"

Use this endpoint to delete a pending personal document.

HTTP Request

DELETE https://api.datatrust.fr/document/<string:digest>

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of the document.

Signatures

With Datatrust you can really easily certify all your data, taking advantage of the many powers of the blockchain.

But what if certifying the data is not enough and you want to certify your ownership of the data ? Datatrust lets you do that and handles for you all the complexity of the operation

General Operation

We designed this solution so that it is really easy for you to use, without sacrificing on the power of cryptographic signatures.

It mainly relies on a light web-service that we may help you deploy in less than 10 minutes ! This web-service will hold your cryptographic keys so that only you control them. Anytime you want to sign a document, this web-service will sign it for you and Datatrust will certify the cryptographic signature, proof of your ownership, on the blockchain.

Attach New Signature

To attach a new signature to a document, use this code:

curl "https://api.datatrust.fr/document/<string:digest>/signature" \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -d '{
        "publicKey": "1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1",
        "signature": "008c2291f78aecc8fe8e448f584858c47eb1023d9ad92957490bd5023d3caebf35d6178514572d9afbb239e4ea08bb4b02cefd7c2bd1a82fd4e8fdde4b1ae05c00"
    }'

The above command typically returns a JSON structured like this, representing the signature and its anchoring status on the blockchain:

{
    "anchor": {
        "standardProof": {},
        "status": "PENDING"
    },
    "signature": "008c2291f78aecc8fe8e448f584858c47eb1023d9ad92957490bd5023d3caebf35d6178514572d9afbb239e4ea08bb4b02cefd7c2bd1a82fd4e8fdde4b1ae05c00",
    "signatureDigest": "c00da6b420007ca877bd2525c126643ca87a475b90dbcab4a2f999d3b93bbf32",
    "signeePubKey": "1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1",
    "signeeAddress": "1a642f0E3c3aF545E7AcBD38b07251B3990914F1"
}

Once the signatue is attached to the corresponding document, you can find details about all related signatures by fetching details about the document. You may for instance track there the status of the signature anchoring.

curl "https://api.datatrust.fr/document/<string:digest>" \
    -H "Authorization: Bearer my_jwt_here"

The above command may thus return JSON structured like this:

{
    "anchor": {
        "standardProof": {},
        "status": "PENDING"
    },
    "creator": {
            "email": "alice@mycompany.co",
            "name": "alice"
    },
    "features": {
        "digest": "eae96cb12d3860810113a9d2ad8b2e9808c6a6d053ac66e408b0e83445f10662",
        "name": "My document name",
        "description": "My document description",
        "type": "image/jpeg",
        "tags": [
            "tag#0",
            "tag#1"
        ],
        "size": 241867,
        "creationTimestamp": "Tue, 06 Nov 2018 04:58:01 GMT",
        "discoverable": true,
        "archived": false,
        "storedOnline": false,
        "webhook": "https://personal.webhook.co"
    },
    "signatures": [
        {
            "anchor": {
                "standardProof": {
                    "@context": "https://w3id.org/chainpoint/v2",
                    "anchors": [
                        {
                            "sourceId": "26839ac7e2659d0cf10430f517d2a29144c94ba324e93ff1a550ce2690b31af4",
                            "type": "ETHData"
                        }
                    ],
                    "merkleRoot": "55a84f72a47aa2cb831d5896b78f60bc5ee9e82f2299f5fc8f61b0166b257122",
                    "proof": [
                        {
                            "left": "672a32e7b406bdfb3af2d425a59138d4fd4b49d59b784d317257293c66c30cee"
                        },
                        {
                            "right": "514954169c8e876052ee45bc66c41cef8a961ab6e095da1e28e62a6fce962f75"
                        }
                    ],
                    "targetHash": "c00da6b420007ca877bd2525c126643ca87a475b90dbcab4a2f999d3b93bbf32",
                    "type": "ChainpointSHA256v2"
                },
                "status": "VALID",
                "timestamp": "Tue, 06 Nov 2018 05:00:10 GMT"
            },
            "signature": "008c2291f78aecc8fe8e448f584858c47eb1023d9ad92957490bd5023d3caebf35d6178514572d9afbb239e4ea08bb4b02cefd7c2bd1a82fd4e8fdde4b1ae05c00",
            "signatureDigest": "c00da6b420007ca877bd2525c126643ca87a475b90dbcab4a2f999d3b93bbf32",
            "signeePubKey": "1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1",
            "signeeAddress": "1a642f0E3c3aF545E7AcBD38b07251B3990914F1"
        }
    ],
    "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93"
}

This endpoint registers a cryptographic signature and attaches it to a corresponding document before certifying it on the b.

HTTP Request

POST https://api.datatrust.fr/document/<string:digest>/signature

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of the signed document.
publicKey hex-char string Public part of the key used to sign the document.
signature hex-char string Cryptographic signature of the document digest.

Query Results

Feature Description
anchor Details related to the certification process.
signature Cryptographic signature.
signatureDigest SHA256 hexadecimal digest of the signature.
signeePubKey Public part of the key used to sign the document.
signeeAddress Identifying cryptographic address of the signee, computed from signeePubKey.

Document Storing

Besides certifying your documents and associated cryptographic signatures, Datatrust allows you to store source documents.

Upload Source Document

To store a source document, use this code:

curl "https://api.datatrust.fr/document/<string:digest>/source" \
    -X POST \
    -H "Authorization: Bearer my_jwt_here" \
    -F "file=@/path/to/source/document"

This endpoint allows you to store your original documents.

You first need to register a new document using the dedicated endpoint. Only then will you be able to upload the source document with this endpoint.

HTTP Request

POST https://api.datatrust.fr/document/<string:digest>/source

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of the document.
file File Source document.

Download Source Document

To download a source document, use this code:

curl "https://api.datatrust.fr/document/<string:digest>/source" \
    -H "Authorization: Bearer my_jwt_here"

This endpoint downloads a stored source document identified by its digest.

HTTP Request

GET https://api.datatrust.fr/document/<string:digest>/source

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of the document.

Delete Source Document

To stop storing a source document, use this code:

curl "https://api.datatrust.fr/document/<string:digest>/source" \
    -X DELETE
    -H "Authorization: Bearer my_jwt_here"

This endpoint deletes the online copy of a source document identified by its digest.

HTTP Request

GET https://api.datatrust.fr/document/<string:digest>/source

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of the document.

Verify Certification

Verify from Digest

To verify the status of a certification, you can use this code:

curl "https://api.datatrust.fr/document/verify" \
    -H 'content-type: application/json' \
    -X POST \
    -d '{
        "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1"
    }'

Most of the time, the above command returns a JSON object structured like this:

{
    "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
    "observableDocs": [
        {
            "accountName": "my company",
            "publicId": "11e8376365fe490aabd376147334646aeb04d2e39a4df744bbb51c7dcd0ffe93",
            "timestamp": "Sat, 30 Jun 2018 17:00:13 GMT"
        }
    ],
    "receiptFor": null
}

If you used the route with the digest of a previously downloaded PDF certificate, the above command may return a JSON object structured like this:

{
    "digest": "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1",
    "observableDocs": [],
    "receiptFor": "f1d478686c5262ebcded59ed67fb919ff8ed9428a4f72bcee1a43932bf10959e"
}

This endpoint helps you verify the status of a document certification from its digest or the digest of a PDF certificate.

HTTP Request

POST https://api.datatrust.fr/document/verify

Query Parameters

Parameter Type Description
digest 64-hex-char string SHA256 hexadecimal digest of either the document or its PDF certificate.

Query Results

Feature Description
digest Queried digest.
observableDocs In case the queried digest corresponds to observable documents anchored by third users, this field holds a list of objects specifying, for each of these third users, the name of the account and the time of certification among other information.
receiptFor In case the queried digest is recognized as the digest of a downloaded PDF certificate, this field indicates the digest of the related certified document.

Webhooks

When creating new documents, you may provide an optional webhook value containing a URI to your services. Once certification is actually triggered, a POST request will be made to that URI with serialized document details in its body.

Your webhook will receive a string containing a serialized JSON object structured like this:

[
   {
      "anchor":{
         "standardProof":{
            "@context":"https://w3id.org/chainpoint/v2",
            "anchors":[
               {
                  "sourceId":"44af79c4669917b035dff7739a67d1e22b32e08ebd22d6ff3dbde3a2424e45ac",
                  "type":"ETHData"
               }
            ],
            "merkleRoot":"71d68559f71f3484ef78a16d74a70f7279b23c61006e9b46c3f8a591b2080334",
            "proof":[

            ],
            "targetHash":"71d68559f71f3484ef78a16d74a70f7279b23c61006e9b46c3f8a591b2080334",
            "type":"ChainpointSHA256v2"
         },
         "status":"VALID",
         "timestamp":"2019-09-17 16:43:34"
      },
      "creator":{
         "email":"user@datatrust.fr",
         "name":"user"
      },
      "features":{
         "archived":false,
         "creationTimestamp":"2019-09-17 16:43:16.396000",
         "description":"foo",
         "digest":"71d68559f71f3484ef78a16d74a70f7279b23c61006e9b46c3f8a591b2080334",
         "discoverable":false,
         "name":"YourFile",
         "size":8038,
         "storedOnline":false,
         "tags":[
            "foo",
            "bar"
         ],
         "type":"txt",
         "webhook": "https://personal.webhook.co"
      },
      "publicId":"1d849e0175fc45218d90fee0a98466702bd83af34e6a433a8a803a83844bb288",
      "signatures":[

      ]
   }
]

Get PDF Receipts

To download PDF receipts, use this code:

curl "https://api.datatrust.fr/document/pdf-receipt" \
    -H "Authorization: Bearer my_jwt_here" \
    -H 'content-type: application/json' \
    -X POST \
    -d '{
        "digestsOrPublicIds": [
            "3581fa736f3b5f0e7af5c5d0e115be07b8be839063ff78a315a37224b3c624d1"
        ]
    }'

Note that the authentication header is not needed if you only download certificates of documents you own, and not of observable documents from other users.

To verify a document certification in a trustless manner, both the original document and an associated receipt are needed.

This endpoint helps you download PDF receipts for personal or discoverable documents identified by their digests or public IDs.

HTTP Request

POST https://api.datatrust.fr/document/pdf-receipt

Query Parameters

Parameter Type Description
digestsOrPublicIds list of strings List of document digests or public IDs.

Chainpoint

Proof of anchoring provided by Datatrust are fully compliant with Chainpoint v2 standard.

This standard is largely adopted among certification services and many tools support it.

With our API, you will find relevant information under the standardProof key of each document.

Let's for example use the chainpoint-validate open npm package to verify a document. Here is its receipt, containing a Merkle proof.

{
   "@context": "https://w3id.org/chainpoint/v2",
   "anchors": [
      {
         "sourceId": "b6d379a96ff8c9a447e328d0eb5798fc59bc8f9eff980d7dfc7c95e44e49e63a",
         "type": "ETHData"
      }
   ],
   "merkleRoot": "795036e61940503d5f19b7f607a7f67f6d7d5ab8decfeb6fd8f7427999f2d87c",
   "proof": [
      {
         "right": "decadf8d213759e57b30474f2fd58ac71d209335cb6c88bfa2b136c1dab88916"
      },
      {
         "right": "27d628b91da4b095999bd422c4f1ff6888db6f1a601b387aefb9a643cbcc8a78"
      },
      {
         "right": "7db7120f1d3e1646b2615f1f31c636d19b45d93b2bfd5e33c16002a1c317f2fa"
      },
      {
         "left": "ee4b186ada95a2e6996bf31a6d787cc6d439e7af6c87f83c551b9b185c13e594"
      }
   ],
   "targetHash": "0053973fe8ab5279685a4a4b5bba295fdd019f3a26654d42184c8c11ae12eec9",
   "type": "ChainpointSHA256v2"
}

After installing the library (yarn add chainpoint-validate) and defining a receipt variable holding the above data, you may validate the proof using this code :

const cb = (err, result) => {
  if (err) {    console.log('an error occurred');    console.log(err);
    return;
  }
  console.log(result);
};

chainpointValidate.isValidReceipt(receipt, false, cb);

This should print the following result in which the isValid key approves the validity of the certification, with the related merkleRoot. The sourceId points to the Ethereum transaction responsible for the actual anchoring. You may find it in an explorer such as Etherscan.

{
  "isValid": true,
  "merkleRoot": "795036e61940503d5f19b7f607a7f67f6d7d5ab8decfeb6fd8f7427999f2d87c",
  "anchors": [
    {
      "type": "ETHData",
      "sourceId": "b6d379a96ff8c9a447e328d0eb5798fc59bc8f9eff980d7dfc7c95e44e49e63a"
    }
  ]
}

OpenAPI

This API is specified and fully compliant with OpenAPI (former Swagger) standard. The full specification can be found here.

A visual editor is also available online.

Every tools supporting Swagger specifications should work out of the box. You may for instance import request collections in Postman or Insomnia using the specification URI: https://developer.datatrust.fr/openapi.yaml.

In Postman, just click on Import and Import from link.

postman

In Insomnia's preferences, select Data and Import from URL.

insomnia

Changelog

2.3

Released on June, 1st 2020.

2.2

Released on April, 30th 2020.

2.1

Released on September, 27th 2019.

2.0

Released on November, 6th 2018.

v1.2

Released on July, 2nd 2018.

v1.1

Released in April, 2018.

v1.0

Released in April, 2018.