User Management

Inviting Users to an Organisation

In this system, user management follows a two-tier model with root organisations and sub-organisations. Users associated with a root organisation have access to all affiliated sub-organisations and can perform specific actions across these levels, while sub-organisation users are restricted to their own sub-organisation.

Invitation Process

Inviting a user involves creating an invitation, where an existing user specifies the invitee's email and role. This structure uses Role-Based Access Control (RBAC) to manage access, ensuring users can only access resources within their designated organisation.

The following steps outline the invitation process:

Creating an Invitation:

An authorised user initiates an invitation to a new user by specifying the invitee's email and desired role (such as “user”).

Endpoint:

POST {{base_url}}/api/organisation-invitations?organisation_id={{organisation_id}}

Request Payload:

{
  "organisation_id": "{{organisation_id}}",
  "email": "invitee@example.com",
  "role": "user"
}

Sample Response:

{
  "id": "4703c390-b36e-433a-95b1-d794b9f59b9c",
  "organisation_id": "2e8ccd2b-f83f-4fe8-b845-c54ab7808715",
  "email": "invitee@example.com",
  "role": "user",
  "status": "pending",
  "created_at": "2024-05-28T16:12:10.831Z",
  "updated_at": "2024-05-28T16:12:10.831Z",
  "deleted_at": null
}

Invitation Notification:

The invited user receives an email with a link to join the organisation and is informed of their designated role. The interface for this invitation is illustrated below:

User Accepts Invitation:

Upon clicking the link, the invited user is directed to complete onboarding. The system updates their status as accepted.

Endpoint:

PATCH {{base_url}}/api/organisation-invitations/:id

Request Payload:

{
  "status": "accepted"
}

Affiliation Assignment:

Once the invitation is accepted, the user is officially affiliated with the organisation and inherits permissions according to their role.

Access Control and Permissions

This invitation process is closely tied to the organisational hierarchy:

• Root Organisation Users: Can access and perform actions on all sub-organisations under their root organisation. They have visibility into users across both root and sub-organisations.

• Sub-Organisation Users: Can only view and manage resources within their assigned sub-organisation. They cannot access or interact with resources belonging to the root organisation or other sub-organisations.

Example Scenario

To illustrate permissions:

• Scenario A: A user in the root organisation “ABC Holdings” can invite new users to “ABC Holdings” or any sub-organisation, like “ABC Holdings - Child 1.”

• Scenario B: A user in “ABC Holdings - Child 1” is limited to viewing and managing resources only within “ABC Holdings - Child 1.” They cannot see users or resources associated with the root organisation.

This RBAC-based model ensures clear separation between root and sub-organisation operations, aligning permissions with the hierarchical structure.