Latest revision as of 12:45, 24 April 2024

Go to API overview

About this page

This page provides a detailed explanation of API authentication. If you are working with a 3rd party software company who has used our API before, please see working with existing API partners

API Access Overview

API access requires being a user of the system. A user in this context is anyone who has access to your data. Each user has a 2 sections on their record which control this:

• The Website and Call-round Access section controls access to your data via our website, and/or our mobile app, Call Round.
• The 3rd Party Systems section controls the access to your data that other systems have via the API

Using this approach, there are 3 possibilities:

• Website/Call-round access only. This will be most users of the system doing day-to-day tasks
• API access only. This could be to migrate data in from other systems, reporting dashboards etc
• Both. An example of this would be if Alice sometimes logs in via the website, and sometimes using a 3rd party app. Alice's access controls are the same in both situations, i.e. she will have the same access to branches, projects and fields.

API Keys

Instead of a user name and password, the API grants access based on three headers:

• Source. Identifies the 3rd party software provider. If Example Software Ltd supplies a number of Dizions clients, they will use the same Source key for all requests. The Source key is provided, and periodically updated, via text message.
• Org. Identifies the charity or company, and the system type. So Example Charity's Live system will have a different Org key to Example Charity's Training system. The Org key can be viewed on the 3rd Party Systems section of the user record in the web application.
• User. Identifies the user within the charity or company. The User key can be created or changes on the 3rd Party Systems section of the user record in the web application.

If you want to test that you have the keys correct, it's useful to call:

[GET] https://api.dizions.co.uk/v2/business/configuration

because it does not apply any access checks beyond checking the keys are correct.

Managing users

The settings on a user record (User Group, project access, branch access etc.) control what a user can see and do. This is broadly the same whether the user is using the website or the API. The new main exceptions are:

1) The See My Own Client feature in the web app is not implemented in the API.

2) The IP address restrictions are applied to your entire API connection, instead of the user group based restrictions in the web app. Registered administrators can request new IP addresses by emailing support@dizions.co.uk

Remember, that as a system administrator, you are responsible for controlling who has access to your data, whether via the website, Call-round or a 3rd party application. Switching off a user is the same regardless - make them inactive on their General Details section. To create a new API user:

• In the web application, click the Settings Cog > User Access > Users. Click Create New User
• Fill in the General User Details as normal
• On the Website Access section, consider un-ticking the Charitylog / Crossdata if you want this user to only access your data through the API. Currently, a user name and password are still required, even if the user has no website access. In the case, they can be made-up, and immediately forgotten. Removing the tick from their website access would prevent them logging in, even if they knew their password.
• Save the record
• On the 3rd Party Systems section, tick the box for the name of the integration that you want to use. This will generate the Org and User keys for the other application.

Using Excel to store credentials for Power Query (Authentication File)

If we are going to use Excel Power Query, we can create a source file to store key information;

• Source Key
• Organisation Key
• User Key
• Host

This will speed things up when using Power Query as we do not need to specify the above details, just where they are. It will give us a template to work with, knowing that the access details are always correct.

Simply open a blank Excel Spreadsheet. In column 'A' add the below list to the first for cells;

• Source
• Org
• User
• Host

In Column 'B' you would add the values for the four options;

• Source - This is the source key that was sent by text message to your organisation.
• Org - This is the Org Key that can be revealed in your User Account.
• User - This is the User Key that can be revealed in your User Account.
• Host - This will be https://api.dizions.co.uk/v2/

Example

From here we would then save the excel file with a suitable name and in a location you will always have access to, the could you My Documents or a network drive. Maybe save the file as Dizions_API_Details.xlsx. When using power query you can use the below example as a header on all queries that you want to run;

let
keyFile = "C:\Users\YourUserName\Desktop\Dizions_API_Details.xlsx",
SourceKey = Excel.Workbook(File.Contents(keyFile), null, true){0}[Data]{0}[Column2],
OrgKey = Excel.Workbook(File.Contents(keyFile), null, true){0}[Data]{1}[Column2],
UserKey = Excel.Workbook(File.Contents(keyFile), null, true){0}[Data]{2}[Column2],
APIHost = Excel.Workbook(File.Contents(keyFile), null, true){0}[Data]{3}[Column2],

Click on the link below to download a template of this file:

Dizions_API_Details.xlsx

See Getting Started with Excel Power Query for further details.