Difference between revisions of "API Authentication"
From Charitylog Manual
(→How do I access the system via the API?) |
(→Using Excel to store credentials for Power Query (Authentication File)) |
||
| (50 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| + | [[API Details| Go to API overview]] | ||
| + | |||
[[File:helpheader_small.png|right]] | [[File:helpheader_small.png|right]] | ||
| + | =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| working with existing API partners]] | ||
| + | |||
=API Access Overview= | =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 | + | 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 | + | * 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 | + | * 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: | 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 | * Website/Call-round access only. This will be most users of the system doing day-to-day tasks | ||
| Line 9: | Line 14: | ||
* 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. | * 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: | 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. | * 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 | + | * 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. | + | * 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<nowiki/>://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 | ||
| − | 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. | + | 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 [[Users#3rd_Party_System_Access:User Account|User Account]]. | ||
| + | *User - This is the User Key that can be revealed in your [[Users#3rd_Party_System_Access:User Account|User Account]]. | ||
| + | *Host - This will be https<nowiki/>://api.dizions.co.uk/v2/ | ||
| + | |||
| + | |||
| + | Example | ||
| + | |||
| + | [[File:API_auth_excel_keys.png]] | ||
| + | |||
| + | 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: | ||
| + | |||
| + | [https://dizions.sharepoint.com/:x:/s/externalsite/EdTqPhvyguVGma6WJ1dAmKYB4qPcJ516zgrnmIL1j6gUtA Dizions_API_Details.xlsx] | ||
| + | |||
| + | See [[Excel Power Query| Getting Started with Excel Power Query]] for further details. | ||
Latest revision as of 12:45, 24 April 2024
Contents
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:
See Getting Started with Excel Power Query for further details.
