Some definitions to start... ✈️

SecuSign a a simple and robust API for electronic signature under a ‘simple’ level compliant to eIDAS regulation. Through the API, Client is able to run a signature transaction for one or more signatories. SecuSign will handle all the steps of signature workflow and cryptographic measures, and the Client keep the responsability to simply provide the url link (generated by SecuSign) to signatories, for signing.

Transaction :

A « transaction » is the full workflow of signature. It is like the « main folder » which is in relation to all the other lower elements which depend on it. To work with SecuSign, first of all Client have to create a new Transaction and then send the file to be signed in this transaction.

The Client is able to create, update, view details, or delete a Transaction. However, some Status of the transaction will prevent certain actions at certain stages (for example, you cannot update a Transaction if the status is already « sent »).

Fields of a Transaction are :

• UID (unique identifier of the SecuSign Transaction)
• Status (created, sent, completed, cancel)
• Sent date
• Created date
• Completed date
• Cancel date
• Webhook URL (a callback that Client can save to be inform about status changes)
• PDF file to be signed

Transaction can be managed throught the following endpoints (all need basic authentification) :

‘Sent’ status is decide by the Client, through /update/. It starts the signature workflow.

Signatory

A « Signatory » is the user of the service, who was requested by the Client to sign the Transaction’s PDF document. At least, 1 Signatory should exist in relation with a Transaction to be able to pass its status to ‘Sent’.

Endpoints for Signatory are :

The signature workflow for Signatory is made up of 3 steps : Identification, Authentification, Signature.

Identification

Each Signatory has to be identified by an Identity Provider to be able to sign the Transaction. As long as the Signatory’s identity is not yet approved by an Identity Provider, Signatory will be unable to go to the next step (Authentification).

Authentication

This step is fully managed by Datasure through the SecuSign workflow, and consists of authentication of the Signatory which has been previously identified by a Identity Provider. When creating a Signatory, the Client defines which kind of authentification he wants for this Signatory (for example, « sms »).

An Authenticate Token is generated when the Signatory wants to sign. In the case of sms, it sends an OTP through Signatory’s phone to confirm. When the OTP is confirmed, it validated the Authenticate Token and unlock the cryptographic signature (next step).

Signature

This 3st (and last) step is about signing the PDF document. This step is only possible if Identification and Authentification steps have been successfully passed. This step will create the Cryptographic signature in the PDF document (PAdES format) and add an additional final page to the pdf as a visible signatures certificate.

Authenticate Token

Depending the type of Authentification asked by Client for the Signatory, an Authenticate Token will be generated when the Signatory attempt to sign, after being successfully identified. This Authenticate Token will be permanently link to the Signatory of the Transaction only when the challenge is successfully passed.

Identity Provider

Identity providers are recognized by Datasure according to its policies. This may consist of any type of provider specializing in identity verification, or any identity federation system, or even the Client itself if Datasure has delegated this responsibility to him, under a delegation policy.

IdP are able to validate all Signatories that have been created with the indication that the identity verifier is this one. In order to do this, IdP must receive a private_key from Datasure to identify its API request.

Diagram of integration Client-Datasure

Complete workflow example

Here is an example from A to Z about what Client has to do to create a full workflow of electronic signature with SecuSign API.

1 - Create a Transaction

A new transaction has to be created 📁, with all the details needed :

Reference : https://docs.datasure.net/reference/48f673477a48975ddbd097eb622b62eb

You receive this kind of answer when Transaction successfully created, and you need to keep the uid of the transaction :

{ "uid": "5c7955f7-fe96-48c7-bff3-d621f7482b8b", "status": "created", "created_at": "2024-01-27T08:45:54.000000Z" }

2 - Create a new Signatory

You now have to create one or more signatories 👨 👩, attached to the Transaction created. 📁

Reference : https://docs.datasure.net/reference/1f44f72050425ae5e06569c07aa365b8

You receive this kind of answer :

{ "uid": "8a6ff96d-196f-40a4-80af-abe4f61f743b", "firstname": "John", "lastname": "Doo", "phone": "33651836133", "email": "[[email protected]](<>)", "language": "FR", "created_at": "2024-01-27T08:51:58.000000Z", "transaction_uid": "5c7955f7-fe96-48c7-bff3-d621f7482b8b", "signatory_url": "https://my.datasure.dev/secusign/transaction/5c7955f7-fe96-48c7-bff3-d621f7482b8b/8a6ff96d-196f-40a4-80af-abe4f61f743b/workflow" }

3 - Approve the signatory Identity

Depending the level of signature (simple, advanced or qualified), the identity verification process is different. 🛂

Identity verification for Simple level

For Simple signature level, the identity verification is automatically approved as soon as you're creating the new signatory.

Identity verification for Advanced level

In order to created advanced electronic signature (AES), Datasure will request Certification Authority (CA) for a signature certificate linked to your signatory. Datasure authorize Clients to verify the identity after deleguate this responsability and creating an Identity provider uid and private key for them (request support to have one).

You can validate any signatory with AES thanks to your own Identity Provider UID.

You must approve the Identity of the signatory after having check its identity in accordance with Datasure policies for this level. When you have successfully check the signatory identity, you can approve the signatory with this request :

Identity verification for Qualified level

[Soon to come]

4 - Give the URL of the SecuSign workflow to your Signatory

When the identity of your Signatory is successfully verified by an IdP, you want to ask him to sign. Client keep the responsability of this, so you have to send to him the URL provided by Datasure (signatory_url) at the signatory creation step. 📧

By the way, the signatory_url can also be build by yourself at any time : https://my.datasure.net/secusign/transaction//<uid of signatory/workflow /

5 - Signatory is signing the document

The front workflow has 3 steps : Identification (it will be pass automatically if the user is already identified by Idp), Authentification, Signature. ✏️

Step 1 (Identification) :

Step 2 (Authentication)

Step 3 (Signature) :

Signature step will add the final page with information about the signatory, and also the cryptographic seal of Datasure for each Signatory.

The signed PDF is archived in relation with the concerned Signatory. All subsequent signatories, from a chronological point of view, will be presented for signature with the latest up-to-date document (i.e. possibly signed by the previous signatory).
A transaction can handle up to 4 signatories maximum.

6 - Get transaction information

At this point, you may want to be inform when all signatories have successfully signed the document. The transaction will pass to status « Completed » when all is done, and you can trigger your own app by the webhook callback URL you can register to the transaction when you created it.
You then can request any transaction details at any time (especially on the trigger event). If the status if on Completed, the API will also give you a temporary direct url ton download the signed pdf and the related evidence file.

7 - Get evidence file

You also can retrieve the evidence file (PDF, JSON, or XML) at any moment of the workflow. 🔐

Reference for PDF Evidence File : https://docs.datasure.net/reference/d208f0e22092ec2cf5139a441c560f2d