Staff account demotion

This article describes how an organization's administrative account may be demoted to a regular learner account through an API integration.

The Drillster platform distinguishes two types of managed accounts:

1. Administrators – also known as staff accounts. Depending on permissions, adminstrators are there to manage groups, catalogs, content and more.
2. Learners – these are regular accounts limited in functionality to the consumption of content. Typically these users are members of one or more of the organization's groups.

The term “managed account” means that the account is owned by the organization and could ultimately also be deleted by the organization. This applies to both administrative and learner accounts.

Simply speaking, an administrator account can be turned into a regular learner account by having another administrator call the DELETE /api/2.1.1/organization/self/staff/{account} endpoint. Complications arise if this administrator is still a group manager.

Revoking group management access

Before an administrative account can be turned into a learner account, the caller must ensure that the target account does not currently have MANAGE or VIEW access to any of the organization's groups.

To determine the groups that a particular staff user is a manager of, call the GET /api/2.1.1/groups/staff/… endpoint. This returns the list of groups that the user is managing. Note that the output is paginated, so multiple calls may be required to get the entire list.

If this yields any managed groups, the management permissions need to be revoked. This can be achieved by calling the DELETE /api/2.1.1/group/{group}/staff/{account}/{permission} endpoint for each of the identified groups.

As an added complication, this endpoint must be called with the exact group permission, VIEW or MANAGE that applies to the administrator in order for the permissions to the group to be revoked. There is currently no endpoint available to determine this for a specific user. One could call the GET /api/2.1.1group/{group}/staff endpoint which returns the entire list of group managers together with their permissions.

Alternatively, and probably more pragmatic, one could simply call:

1. DELETE /api/2.1.1/group/{group}/staff/{account}/MANAGE first, and if that fails, call:
2. DELETE /api/2.1.1/group/{group}/staff/{account}/VIEW.

This should ensure that the user in question loses management access to the group.

Demoting the administrator

Once the caller has made sure that the administrator to be demoted no longer has any management access to any groups, the account can be demoted by calling DELETE /api/2.1.1/organization/self/staff/{account}.

As a result, all management related permissions are removed from the account. Any practice and test results will be kept. As mentioned, the user does not lose access to the account, and should still be able to log in into Drillster in the same manner.

Things to note

The API calls described above should be executed by a service account user with “super group management” access (also known as a groups administrator). Drillster's group management structure is designed in such a way that it should not be possible to end up with groups that have no manager. By having a groups administrator set up for the service account it is both guaranteed that the caller is able to execute the various API calls, but also it ensures that each group has at least one administrator.

Lastly, one could decide to reverse the steps outlined above, and to optimistically try to demote an administrator account to see if it succeeds. If that fails, one can embark on revoking any group management permissions. If it is known beforehand that very few administrative users are group managers, this could be a worthwhile strategy.