Overview

Complyfile is a secure web-based platform that assists an organisation in managing the legal requirements surrounding the on-boarding, and continued administration, of individuals that represent that organisation in a supervisory or public-orientated capacity. It is particularly suited to voluntary or charitable organisations that place their representatives in a supervisory capacity over young or vulnerable individuals.

The Complyfile platform is comprised of three distinct components:

• A Microsoft Azure SQL Server database
• A publicly accessible web application
• A secure REST based web service API

This document outlines the purpose of the web service API component, provides an overview of the functions available and offers some suggestions on the types of service the API can offer to organisations that already subscribe to the Complyfile platform. The document does not include any information on the website or the database that supports the website and web service API.

The document is intended for individuals with a technical understanding of IT systems, and in particular those with a knowledge of integrating disparate systems using web services, but does not provide sufficient information to allow developers to integrate with the API. Information for developers wishing to use the services provided by the API is provided in our systems integration guide.

Architecture

The following diagram outlines the structure of the Complyfile platform, indicating the use and interoperability of the different components used in the operation of the platform.

The web service API acts as a conduit between the Complyfile application and the platform’s database. All transactions requested by end users, executed using the web application, are routed through the web service API.

The web service API can offer services to third party applications that wish to engage in the activities offered by the Complyfile platform. The web service API is a two-way conduit. It can receive inbound requests from external applications to perform specific actions and it can perform outbound requests to external client web services whenever an action occurs on the platform.

Security

There are numerous security authentication mechanisms available to secure external web services to ensure that only the data applicable to a registered organisation can be obtained or updated by that organisation. These mechanisms include:

• Basic authentication
• Session based authentication
• Token based authentication
• Delegated authentication (OAuth/OpenId)

Numerous articles have been written about securing websites and web services. One such article, providing a concise and clearly written overview, can be found at:

https://github.com/teesloane/Auth-Boss

The Complyfile web services employ a token based authentication approach using the JSON Web Token (JWT) token structure, implemented using the standard Microsoft implementation for .NET and secured using HTTPS. Tokens are returned from registration and login requests and remain valid for the period of time stipulated by the web service client during those initial requests. This token must be provided with all further web service requests for the duration of the session. Any web service requests containing an invalid or expired token will be refused by the server. The following scenario provides an overview of the communication between client and server during a single session:

• A client application invokes the Complyfile Login method, passing a registered email address and password and a session duration of 30 minutes.
• The Login method generates a new token containing information about the user account and attaches a session expiry time 30 minutes from the current date and time.
• The client application attempts to update a volunteer record by invoking the Complyfile Volunteer method, passing new information for the volunteer and providing the session token in the Authorization HTTP header value.
• The server decodes the properties of the token provided in the Authorization header and checks the expiry date property to ensure the token has not expired. The server then updates the volunteer record with the information provided and alters the expiry time on the token to ensure it remains valid for a further 30 minutes from the time of the latest request.
• The client does not make any further requests for a period of 45 minutes and then attempts to send a volunteer invitation by invoking the Volunteer/Invite method, passing the session token in the Authorization HTTP header value.
• The server again decodes the properties of the token provided and checks the expiry date property. As server determines that the token expired 15 minutes  earlier and refuses the request with a 401-Unauthorized response.

Implementing security in this manner ensures that the client’s credentials are only provided during the initial authorisation handshake and are not required, and cannot therefore be  compromised, during any further requests during that session. Session security is further strengthened through the use of application keys, which can be generated whenever required by the client, and can be revoked just as easily.

WebHooks

A webhook is a HTTP callback request, a process in which a web service or other process can invoke external web services provided by other third parties. For Complyfile, webhooks can be available for a number of processes, including:

• Inviting a volunteer
• Updating volunteer details
• Changing the status of volunteer records

Individual organisations can specify webhooks for each of the available Complyfile processes that offer support for callbacks. These webhooks will then trigger whenever those processes occur, allowing the third party service to respond to the webhook and perform additional tasks.

The following workflow provides an example of a webhook in operation:

• A client application invokes the Complyfile Login method, passing a registered email address and password and a session duration of 30 minutes.
• The Login method generates a new token containing information about the user account and attaches a session expiry time 30 minutes from the current date and time.
• The client application then invokes the Volunteer/Invite web method to invite a new volunteer to the organisation. The server creates the new volunteer record and sends the invite to the volunteer by email. The server then checks to see if the organisation has registered a webhook for volunteer invites and, on finding the webhook configuration, proceeds to invoke the external web service.
• The organisation has previously deployed a public web service that is authorised to communicate with their internal systems and, on receiving the request from the Complyfile API, proceeds to update the organisation’s internal database using the invitation details provided in the request.

Webhooks provide a powerful mechanism for extending an application and allowing it to integrate with internal and external applications. Webhooks operate asynchronously, and do not need to wait until the callback operation completes. Complyfile webhooks operate using standard REST operations, and follow the usual GET/PUT/POST/DELETE verb rules required by that standard.

Webhooks, once configured, will operate when events occur in the web application or the API. In the above example, the same webhook would be executed if the invite was created by an end-user performing the operation in the application.

REST API

API Callback