Integrate with Signicat

Signicat is a provider of digital identity solutions all over Europe. Products include identity proofing, authentication and electronic signatures. In this guide, we will specifically take a look at how to send a PDF file for digital signatures (e-signature).

To get started with this guide, you a paid account or a free test account and get the required API credentials to integrate with Signicat. If you don’t have done this yet, you can do so by clicking this link.

Step 1 - Create API Client in Signicat

All communication with the API requires a Bearer token. A Bearer token is valid a certain amount of time, and a new Bearer token may be retrieved using the same API with a given client ID and secret as input.

You need to get the Client ID and Secret from Signicat.

• Log into Signicat (link to Test environment here).

• Go to Account -> API Clients and create a new client. Name it whatever you want.

• Choose OAuth/OpenID Config and tick off identity, event, document_file, document_read and document_write under Scope.

• Copy the Client ID and Secret to your notepad as you will need it later.

Step 2 - Create Secrets in Appfarm Create

Inside Appfarm Create, go to Security -> Secrets and add the following Secrets:

• Signicat Client ID: Tick Environment Specific. Secret Type should be String. Copy the Value saved in step 1 into Development and Test. The reason for this is that we have retrieved the Client ID and Secret for the Signicat Test Environment in Step 1, and we would like to use it only for the Appfarm Development and Test Environment. You will need to get another Client ID and Secret for the Signicat Production Environment (from the Signicat Production Dashboard)

• Signicat Client Secret: Tick Environment Specific. Secret Type should be String. Copy the Value saved in step 1 into Development and Test.

• Signicat Endpoint Get token (optional): Secret Type should be String. Value should be https://api.signicat.io/oauth/connect/token. We recommend saving the hostname we integrate towards as a Secret, and using the Secret in Web Requests instead of hardcoded URLs in Web Requests. The URL for getting Bearer token is the same for Test and Production, hence no "Environment Specific" setting.

• Signicat Bearer Token: Tick Environment Specific. Secret Type should be String. Leave values blank.

The Signicat Bearer Token should be updated regularly with the Bearer Token received from Signicat from a Service (see next 2 steps). So, the Service Account that should run the Service should be a member of a dedicated Role, and that Role needs access to update this Secret as well.

• Identify the Role, or create the Role, for the Service Account that should run the Service. If no such Service Account or Role exists: Create the Role, e.g. Signicat Service Role, and the Service Account Signicat Service User (make it a member of the Signicat Service Role)

• Go to Security -> Permissions -> Advanced, and locate the settings allowing Signicat Service Role to Update Secret Signicat Bearer Token.

Step 3 - Create the Service and Schedule for getting the Bearer Token from Signicat

Create a Service for getting the Signicat Bearer Token. The Service Endpoint should execute an Action with the following Action Nodes:

1. Action Node: Web Request

In the above screenshot, the Web Requests connect to the URL defined in Step 1. Also:

• Request Header: Add an entry Authorization with a value defined by the function return Basic ${signicatClientSecret} (signicatClientSecret is the secret defined in Step 2, added as a Function Parameter)

• Method: POST

• Body Type: URL-encoded

• Body Content: 2 entries:

  • Key: grant_type, Value: client_credentials

  • Key: scope, Value: document_read document_write document_file event

• Result Mapping: Create a Service Variable Access Token (string). Set up the Result Mapping as follows:

2. Action Node: Update Secret

Add the Update Secret Action Node. This is where you should update the Secret Signicat Bearer Token with the value received (and temporarily stored in a Service Variable):

Now, you may test this Service from Swagger to make sure it works. When verified, you may create a Service Schedule (running e.g. every 30 minutes) to execute the Service you just created. Remember that the Schedule must be set up with the Service Account defined in Step 2.

Having the Bearer Token automatically updated and all Appfarm Permissions and Signicat Permissions set up correctly, we are now ready to actually send a document for signature.

Step 4 - Action for sending a document to Signicat

In this step, we go through the steps for sending a document to Signicat for electronic signature. Note that in this process, we send the document (as a base64 string), some info and parameters, and the name/email(s) of the signer(s) to Signicat. We will get back an ID of the Document as well as the URL(s) for signing the document. And we may choose in the parameter input to Signicat whether we want Signicat to send the email to the signers, or if we want to use the received URL(s) and send the emails from Appfarm.

Create an Action in Appfarm for sending the Document. You may create the Action in an App or a Service.

1. Convert the PDF to a base64 string

First, add a Web Request as follows:

• URL: The File Content property of the document (stored in Appfarm)

• Method: GET

• Response Type: Arraybuffer

• Result Parser: This is where the "magic" lies: Converting the binary stream into a base64 string. Add the following code to the Result Parser:

let res = new Uint8Array(rawResponseData)
const chunkSize = 10000
const chunks = Math.ceil(res.length / chunkSize)
console.log({ chunkSize, chunks })

let thing = ""
for (let i = 0; i < chunks; ++i) {
  const part = res.slice(i * chunkSize, (i + 1) * chunkSize)
  thing += String.fromCharCode.apply(null, part)
}

let base64String = btoa(thing);
return {base64String}

• Result Mapping: You will need to map base64String to the App Variable or runtime property where you want to store the base64 version of the document temporarily.

2. Send the document for signature to Signicat

See the following link where you can find the URL for the API Endpoint in Signicat, as well as the structure of the JSON to be sent. You will need to set up a Web Request:

• URL: The endpoint, as found in the above link (https://api.signicat.io/signature/documents).

• Authorization: Bearer Token

• Auth Token: The Secret holding the Bearer Token.

• Prefix Bearer Token: Tick this one (added the word "Bearer" in front of the token in the Auth header generated)

• Method: POST

• Body Content: A function returning the JSON. Example:

return `
{
  "title": "Test document",
  "signers": [
    {
      "externalSignerId": "${personID}",
      "redirectSettings": {
        "redirectMode": "donot_redirect"
      },
      "signatureType": {
        "mechanism": "pkisignature"
      },
    }
  ],
  "dataToSign": {
    "title": "${contractTitle}",
    "description": "Contract for signing",
    "base64Content": "${base64String}",
    "fileName": "${contractFilename}",
  },
  "contactDetails": {
    "email": "[e-mail]",
    "url": "https://vendorcomp.com"
  },
  "externalId": "${contractID}",
  "description": "This is an important document"  
}
`

• Result Mapping: You must at least map and save the returned documentId and the URL of the signers (if 1 signer, you may map the property signers.0.url). Also, you should save the property status.documentStatus (the string "unsigned" is returned initially)

If you are sending the emails to the signers, you may now add the Send Email action node(s) for sending the email(s) to the signer(s) with your predefined text, the PDF itself as an attachment (optional) and - most importantly - the URL for signing the document. Note that clicking the URL will open Signicat's solution, where the user must log in and sign the document.

Step 5 - Get notifications when a document is signed, and download the signed file

Until this step, you have functionality for sending a document for signature, and saving the unique Document ID (Signicat's reference to the document) and URL for signing the document. We would like to know when the Document is signed.

There are 2 ways of getting the status of the Document:

1. Use the Status API. Just add a Service with an action that checks the status of all unsigned documents. Let it be executed e.g. every hour or day.
2. Use the Notifications API. You may create a webhook in Signicat's, and a Service Endpoint in Appfarm. Then, connect the webhook to the endpoint, and Signicat will send updates to the document status automatically!

When the status is signed, you may download the file and save it in Appfarm using this API.