Version #

Version 1

Module Type #

Standard

Internal Name #

adminRoles

Status #

Draft

Description #

The Admin Roles Module manages administrative roles. In Version 1, only one role exists: the “Standard” role, which is automatically assigned to all newly created admins. This Standard role is to be hardcoded, no Endpoint will exist for CRUD operations.

The Module have basic error handling.

User Journeys #

getAdminRole #

Name

getAdminRole

Overview

This user journey allows an authenticated admin to retrieve their assigned administrative role from the system. By making a request to the designated endpoint, the admin can view details about the role that is currently linked to their account.

Actors

• Admin User (initiator)

Preconditions

• The admin must be authenticated via the Auth Module (valid JWT Token required).
• The Admin Roles Module must be accessible.

Flow

Primary Flow

1. The Admin User sends a POST request to the /adminRoles/get endpoint, including their valid JWT.
2. The Admin Roles Module verifies the request and retrieves the admin”s role details.
3. The Admin Roles Module returns a success response containing the role information (e.g., RoleID, RoleName).
4. A webhook (adminRoleRetrieved) is triggered to log or process the successful retrieval of the role.

Alternative/Exception Flows

• If an error occurs during role retrieval (e.g., invalid Token, role not found), the system returns an error response:
• { “status”: “Error” }
• and triggers the adminRoleError webhook.

Outcome

The admin”s role information is successfully retrieved and provided in the response, enabling the admin to understand what privileges they hold within the system.

Error Handling

• On error, the system responds with { “status”: “Error” }.
• The adminRoleError webhook is triggered, containing details such as the timestamp, endpoint, and error message.

Postconditions

• On success, the retrieved role details are available to the admin, allowing them to proceed with any actions permitted by their role.
• On error, no role information is returned. The error response and triggered webhook ensure the issue is logged for further investigation.

Triggers

• adminRoleRetrieved: Fired when the admin”s role is successfully retrieved.
• adminRoleError: Fired when an error prevents retrieving the role.

Notes

• In Version 1, only the “Standard” role exists.

Authentication #

Authentication for is managed via the Auth Module. Module-to-module communication in Version 1 does not require Authentication. Internal services can call the Admins Module freely.

Schema #

AdminRoles #

Name	Type	Internal Name	Description
admin_role_id	UUID/String	adminRoles.admin_role_id	Unique identifier for the role
admin_role_name	String	adminRoles.admin_role_name	Role name (always “Standard” in Version 1)
admin_role_description	String	adminRoles.admin_role_description	Description of the role
admin_role_index	Integer	adminRoles.admin_role_index	Index of the role

Functions #

Name	Endpoint	Description	Internal Name	Input	Response
getAdminRole	/adminRoles/get	Retrieves details for the admin role.	adminRoles.getAdminRole	{ “admin_role_id”: “role-admin-001” }	{ “admin_role_id”: “role-admin-001”, “admin_role_name”: “Standard”, “admin_role_description”: “Provides full administrative capabilities”, “admin_role_index”: 1 }or{ “status”: “Error” }

Webhooks #

Name	Trigger	Destination	Payload	Description	Error Handling
adminRoleRetrieved	When an admin retrieves their assigned role.	Log Module	json { “event”: “admin.role_retrieved”, “timestamp”: “2025-03-13T12:00:00Z”, “admin”: { “AdminID”: “admin-001”, “Role”: “Standard” } }	Sends a webhook to the Log Module when an admin fetches their role.	None
adminRoleError	Triggered when an error occurs during the retrieval of the admin role.	Log Module	{  “event”: “admin.role_error”,  “timestamp”: “2025-03-13T12:00:00Z”,  “error”: “Error message details”,  “endpoint”: “/adminRoles/get”}	Sends a webhook to the Log Module containing error details, including the endpoint, error message, and timestamp.	None

Settings #

Not applicable

Clarifications #

• Only one role exists in Version 1.
• The Standard role is used to derive the full set of admin permissions in the Admin Rights module.
• All API requests to this module require prior Authentication via the Auth module.
• The module includes basic error handling as described above.
• No endpoints exist for creating or updating roles; the role is hardcoded for simplicity in Version 1.