NAV Navbar
shell
  • Introduction
  • Roles and Authentication
  • Request Parameters
  • Errors
  • Account
  • User
  • JSON WEB Token
  • Documents
  • Signatures
  • Document Storing
  • Verify Certification
  • Changelog
  • 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 ✔ (limited)
    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
        },
        "flashAnchoringOption": false,
        "logoUrl": "https://mycompany.co/logo.svg",
        "mainPrimaryColor": "#1f9e5b",
        "mainSecondaryColor": "#eaa522",
        "maxNbUsers": 20,
        "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 true, document will instantly be certified once submitted.
    logoUrl string Logo URL.
    mainPrimaryColor string Hex primary color.
    mainSecondaryColor string Hex secondary color.
    maxNbUsers integer Maximum number of users.
    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.

    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"
                },
                "roles": [
                    "subuser"
                ],
                "defaults": {
                    "docDiscoverableByDefault": false,
                    "language": "en",
                    "signatureServerEnabled": true,
                    "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
                    "signatureServerEthKeyId": 0
                }
            }
        }'
    

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

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

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

    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"
        },
        "roles": [
            "subuser"
        ],
        "defaults": {
            "docDiscoverableByDefault": false,
            "language": "en"
        }
    }
    

    This endpoint retrieves all your basic user features.

    HTTP Request

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

    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"
            },
            "roles": [
                "subuser"
            ],
            "defaults": {
                "docDiscoverableByDefault": false,
                "language": "en",
                "signatureServerEnabled": true,
                "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
                "signatureServerEthKeyId": 0
            }
        }
    ]
    

    If you do not have administration rights, the JSON object would be structured like this:

    [
        {
            "features": {
                "email": "alice@mycompany.co",
                "name": "alice"
            }
        }
    ]
    

    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"
                },
                "roles": [
                    "subuser"
                ],
                "defaults": {
                    "docDiscoverableByDefault": false,
                    "language": "en",
                    "signatureServerEnabled": true,
                    "signatureServerURI": "https://signature-webservice.mycompany.co/sign",
                    "signatureServerEthKeyId": 0
                }
            },
            "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.
    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.
    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 account 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
            }
        }'
    

    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,
            "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.

    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,
            "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,
                "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
    }
    

    This endpoint filters your personal documents.

    HTTP Request

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

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

    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
            }
        }'
    

    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,
            "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.

    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
        },
        "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

    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.

    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.

    Changelog

    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.