API Service Accounts
Background
It's possible to create an IoGT account which provides access to the IoGT Data API, without giving that account access to the Admin Panel. You might want to do this if you are enabling an external system to automatically read data from the IoGT API - sometimes accounts like this are called "service accounts".
There are two steps to doing this:
- Create a Group which provides the appropriate permissions
- Create an IoGT account
Creating a Group to Provide Permissions
Using the instructions to create a new user role in IoGT, create a group with a name that clearly explains its function, for example "SERVICEACCOUNTROLE_PartnerA_ProjectB". This will help you keep track of the access you provide.
This group should have no permissions allowed EXCEPT in Page Permissions:
The checkbox in the red square in the Edit column should be checked, and none of the other checkboxes should be checked. This will allow access to the survey/poll/quiz data.
The selection in the green box indicates which surveys/polls/quizzes within the site the account will have access to. Whichever Page is indicated here, the account can access data from surveys/polls/quizzes which are below that Page in the site hierarchy.
By default the green box shows the selection "Root", which means the service account will be able to access all survey/poll/quiz data in your IoGT platform. If you want to limit the account's access to a particular part of the site, you can hover over the word "Root" and then click the button "Choose Another Page". The account will have access to survey/poll/quiz data for Pages which are below that Page in the site hierarchy. You can also select an individual survey/poll/quiz which has no other Pages below it, and the account will have access to only that data.
If you want to specify more than one area of the site hierarchy to give access to, you can press the "Add a Page Permission" button to create a new row in this table. In this new row, be sure that only the "Edit" column checkbox is selected.
Keep in mind that if you have added a survey/poll/quiz as "embedded" in another Page, the Page for the survey/poll/quiz might not be in the same place within the site hierarchy as the Page where it is embedded.
It is important that the permission "Can access Wagtail Admin" is unchecked:
If that permission is checked, the account will be able to access the Wagtail Admin Panel and edit the surveys/polls/quizzes for which they have data access - so it's important to keep it unchecked.
Creating the IoGT Account
Using the instructions to create a new account in IoGT, create an account with a name that clearly explains its function, for example "SERVICEACCOUNT_PartnerA_ProjectB_SystemC". "SystemC" might be the name of the system that will use the account to access the data, like "MOHMisinformationDashboard".
You should give this account the "Role" from the Group that you created earlier. The user shouldn't be given any other role, and should not be set as an Administrator.
Conclusion
With the new service account created, and assigned to a Group, an external system can access specific data on IoGT programmatically and without needing access to the Admin Panel.