As an Org Admin, I want to generate an Org API token that is scoped to a set of Unit(s) so that a user with this token can use the Org API with Unit scoping permissions taken into account

[baszoetekouw]

Use Cases:

1. Orgs have Unit Managers that wish to use the Org API to programmatically manage COs. The Orgs wish to grant that power, but scoped to the Units and not for the whole Org.
2. Orgs want to give particular application owners the ability to manage COs. They want to do this without giving the application owner the ability to manage ALL COs within the org. They instead want to create Units within which the application owner would have the ability to manage COs using the Unit scoped token.

Org API Route	Description	Should be available to Unit Manager?
POST /api​/collaborations​/v1	Post a new collaboration	✅
DELETE ​/api​/collaborations​/v1​/{co_identifier}	Delete collaboration	✅
GET /api​/collaborations​/v1​/{co_identifier}	Get collaboration details	✅
PUT ​/api​/collaborations​/v1​/{co_identifier}​/members	Update collaboration membership	✅
DELETE ​/api​/collaborations​/v1​/{co_identifier}​/members​/{user_uid}	Delete collaboration membership	✅
PUT ​/api​/collaborations_services​/v1​/connect_collaboration_service	Connect service to collaboration	✅
PUT ​/api​/collaborations_services​/v1​/disconnect_collaboration_service	Disconnect service from collaboration	✅
POST ​/api​/groups​/v1	Post a new group	✅
DELETE ​/api​/groups​/v1​/{group_identifier}	Delete group	✅
POST ​/api​/groups​/v1​/{group_identifier}	Add group membership	✅
PUT /api/groups/v1/{group_identifier}	Update properties of a group	✅
DELETE ​/api​/groups​/v1​/{group_identifier}​/members​/{user_uid}	Delete group membership	✅
PUT ​/api​/invitations​/v1​/collaboration_invites	Put new collaboration invitations	✅
GET ​/api​/invitations​/v1​/invitations​/{co_identifier}	Get open invitations for a given collaboration	✅
DELETE /api​/invitations​/v1​/{external_identifier}	Delete invitation	✅ but needs a check for the invitation {external_identifier}-> CO -> Unit membership relation
GET ​/api​/invitations​/v1​/{external_identifier}	Get invitation details	✅ but needs a check for the invitation {external_identifier}-> CO -> Unit membership relation
GET ​/api​/organisations​/v1	Get organisation including all collaborations	❌ as the endpoint is currently described, unit managers should not be able to do this. Specifically, the unit manager should not be able to get all collaborations, only those which fall under their unit(s)

proposed solution to this last endpoint is just to scope the token to the user's units and return data associated with those units only.

Notes

• Orgs are permanent-ish. Units may come and go. How do we want to tie the lifecycle of the Unit Token to a given Unit? Probably: when Unit ends, token is deleted. Regardless, we must document and make this behavior clear to the user.

[logan-life]

Bas to refine this to determine which of the above listed org API endpoints are in scope.

[logan-life]

SRC is waiting for this.

[logan-life]

Logan to take a first pass then ping Bas for double check.

[ccacciari]

A comment from the support team, data managers, of VU:

Do you know of an easy way to add all existing Yoda COs to the Unit? Looking at https://sram.surf.nl/apidocs/ I can create new COs and update memberships of existing COs, but I don't see a way to update CO attributes.

I think that the request can be translated into the following requirement:

• there should be a procedure to assign, as a bulk operation, existing COs to a unit or remove them. That should be probably in the scope of the Org admin/manager, not in that of the unit manager.