MyWorkPal

Introduction

The MyWorkPal platform provides a RESTful API which can enable external applications to interface with the platform.  A RESTful API is built on HTTP, providing methods such as GET, POST and DELETE to retrieve and/or manipulate data.  

• The API currently resides in Azure.
• All endpoints are protected by TLS 1.2 encryption.  
• All endpoints require authenticated requests.  Any anonymous requests will be denied.  
• The API supports Open ID authentication.  An external client needs to authenticate using a client ID and secret.  If successfully authenticated, a bearer token will be provided.  
• The bearer token will need to be provided with any subsequent endpoint requests.  If an invalid token or expired token is provided, the API will deny the request with a 401 error (Unauthorised access).
• If a request is made to an endpoint that the API client does not have access to, a 403 error will be returned (Access forbidden)

API Client

To be able to make use of the API, the first thing you will require is an API client.  See How to create API Clients for more details on this.

API Clients are set up on the platform by an administrator with appropriate permissions.  

• The API Clients ID and secret are set by the administrator.  
• API Clients are associated to an administrator account.  This associated administrator account can be given the necessary permissions for an API client to perform certain actions.
• When an API client authenticates, it will impersonate this account for any platform transactions  it might perform via endpoint requests. 
• The API client will only have access to the endpoints that the administrator account has permissions to.
• The API client can be configured to have throttling applied to limit the number of requests made over a specified period.  
• The lifetime of the bearer token for the client is also configurable.

Once an API client has been set up, external apps will use the API client credentials to connect to the API by entering the 

• Client ID
• Client Secret

Base URL / Platform URL

All API URLs referenced in this documentation start with a base part. The base URL is:

https://webapi.{your platform domain}

e.g. https://webapi.myworkpal.co.uk

Tenant ID

This is the numeric ID of the tenant, if you're calling an endpoint that needs to identify a specific tenant. You can get the Tenant ID either from a platform level report or display on a tenant level dashboard widget by adding the code 

Tenant ID: {{tenantid}} 

General response status codes

HTTPs call made to MyWorkPal will return a subset of these general HTTP status codes:

Authentication And Accessing The API Endpoints

All API end points are protected and will only be accessible once an external app has authenticated using an API client ID and secret.  Certain API end points may have further protection and will only be accessible if the API client has been granted the appropriate permissions.

To access an API endpoint, an external app first has to authenticate and obtain a bearer token.  This token contains the details and permissions of the API client which is used by the API to determine access.  See Getting a bearer token for details on how to do this.  Once a bearer token is obtained, the external app will have to provide this bearer token in any API requests.  Failure to do so will result in a 401 Unauthorised status being returned.

Documented Endpoints

Below are the most commonly used endpoints in our system:

• Reporting & data transfer
  • Get Report - stream the data set from a named report or merged report 
  • Transferring data via the Data Transfer Template API's - supporting data exchanges between systems

• Tenant Users
  • Return a list of validated tenant users (/ employees) - obtaining user/employee list details
  • Create User - dynamically creating a new user on the MyWorkPal platform
  • Creating dependants for an employee - dynamically creating a new dependant on the MyWorkPal platform
  • Retrieving all dependants for a specific employee - retrieving all stored dependants for a user
    
  • Retrieve user's documents info - retrieving stored documents information for a user
    
  • Upload user documents - uploading a new user document for a user

• Tenant Configuration
  • Get all tenant document categories - support for creating a document for a user
  • Retrieving all dependant types for a Tenant - support for creating a dependant for a user 
  • Retrieving the Gender List - support for creating a dependant or user
  • Retrieving the Salutation List  - support for creating a dependant or user

General C# Code Example

The following example demonstrates how to connect to an API endpoint to run a report. The steps listed below can be carried out on your appropriate UAT environment to test.  

You will first need to define an API client on the platform via the administration portal.  An API client has an ID and a secret and is used by an external party to connect to the API endpoints.  An API client will require an associated admin account which it impersonates when connecting to the API endpoint.  This account will need to be given relevant permissions to the areas that an external party requires access.  Failure to give the admin account the necessary permissions will result in 401 Forbidden responses.

First create a role with permission to access the areas you intend this client to interact with. For example, if you want to just give access to run reports create a role named APIReports and with only access to the Tenant > Reports > RunReports permission.

Next create an admin user account that will be used by the API, such as Useraccount for API client. Assign the APIReports role to this account and gave the account access to the appropriate tenants.

Next create an API Client in BackOffice > Users > Api Clients. Associate the ‘Useraccount for API client’ admin user to the API client you've just created.

You can now use this admin account to access the API endpoint with the example C# code below. 

Platform = the URL of your platform

Username = username of the admin account you've created

Password = password of the admin account you've created

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
 
namespace ConsoleApp1
{
    class Program
    {
        static async Task Main(string[] args)
        {
            try
            {
                await ConnectApi();
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }
 
        private class IdpResponse
        {
            public string access_token { get; set; }
            public int expires_in { get; set; }
            public string token_type { get; set; }
        }
 
        private class ReportLine
        { 
            public int SystemId { get; set; }           
            public string ForeNames { get; set; }
            public string Surname { get; set; }
            public string EmailAddress { get; set; }
        }
 
        private class ReportData
        {
            public ICollection<ReportLine> ResultSet { get; set; }
        }
 
        private static async Task ConnectApi()
        {
 
            // Create a new http client and set the base url for it
            var client = new HttpClient();
            client.BaseAddress = new Uri(https://webapi.myworkpal.co.uk); //This url will vary depending on the platform being used
 
            // First you need to get a bearer token to be able to access the api.
            // You do this by posting the client api credentials to a token end point
            var formContent = new FormUrlEncodedContent(new[] {
                new KeyValuePair<string, string>("grant_type", "client_credentials"),
                new KeyValuePair<string, string>("scope", "api"),
                new KeyValuePair<string, string>("client_id", "username"), //This will change for the live implementation
                new KeyValuePair<string, string>("client_secret", "password!") //This will change for the live implementation
            });
 
            var response = await client.PostAsync("/idp/connect/token", formContent);
            var content = await response.Content.ReadAsStringAsync();
 
            // The content received is in Json format.  Parse this json object to retrieve the access token
            var accessToken = JsonSerializer.Deserialize<IdpResponse>(content).access_token;
 
            // Add an authorization header to the http client and add the token.
            // Without this header you will not be able to get responses from the api.
            // Make note of the "Bearer " bit.  It is important to have this
            client.DefaultRequestHeaders.Add("Authorization", "Bearer " + accessToken);
 
            // CALL TO API ENDPOINT  
           
        }
 
    }
}