Role API

The Role API provides endpoints for managing roles and role assignments within the UBU Digital Finance Solution.

Endpoints

Create Role

POST /role/

Creates a new role. Requires the create_role permission.

Request Body

{
  "role_name": "string",
  "role_description": "string"
}

Responses

201 Created - Role created successfully

{
  "role_id": "uuid",
  "role_name": "string",
  "role_description": "string",
  "role_is_active": true
}

400 Bad Request - Validation error

{
  "detail": "Role with this name already exists."
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get All Roles

GET /role/

Retrieves a list of all roles. Requires the view_roles permission.

Responses

200 OK - Roles retrieved successfully

[
  {
    "role_id": "uuid",
    "role_name": "string",
    "role_description": "string",
    "role_is_active": true
  }
]

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get Role

GET /role/{role_id}

Retrieves a specific role. Requires the view_roles permission.

Path Parameters

role_id (UUID): ID of the role

Responses

200 OK - Role retrieved successfully

{
  "role_id": "uuid",
  "role_name": "string",
  "role_description": "string",
  "role_is_active": true
}

404 Not Found - Role not found

{
  "detail": "Role not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Update Role

PUT /role/{role_id}

Updates a role. Requires the update_role permission.

Path Parameters

role_id (UUID): ID of the role to update

Request Body

{
  "role_name": "string",
  "role_description": "string",
  "role_is_active": true
}

Responses

200 OK - Role updated successfully

{
  "role_id": "uuid",
  "role_name": "string",
  "role_description": "string",
  "role_is_active": true
}

404 Not Found - Role not found

{
  "detail": "Role not found"
}

400 Bad Request - Validation error

{
  "detail": "Role with this name already exists."
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Delete Role

DELETE /role/{role_id}

Deletes a role. Requires the delete_role permission.

Path Parameters

role_id (UUID): ID of the role to delete

Responses

200 OK - Role deleted successfully

{
  "detail": "Role deleted successfully"
}

404 Not Found - Role not found

{
  "detail": "Role not found"
}

400 Bad Request - Role in use

{
  "detail": "Cannot delete role as it is assigned to one or more users"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Assign Permissions to Role

POST /role/{role_id}/permissions

Assigns permissions to a role. Requires the assign_permissions permission.

Path Parameters

role_id (UUID): ID of the role

Request Body

{
  "permission_ids": ["uuid", "uuid", "uuid"]
}

Responses

200 OK - Permissions assigned successfully

{
  "detail": "Permissions assigned to role successfully"
}

404 Not Found - Role not found

{
  "detail": "Role not found"
}

404 Not Found - Permission not found

{
  "detail": "One or more permissions not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get Role Permissions

GET /role/{role_id}/permissions

Retrieves the permissions assigned to a role. Requires the view_role_permissions permission.

Path Parameters

role_id (UUID): ID of the role

Responses

200 OK - Permissions retrieved successfully

[
  {
    "permission_id": "uuid",
    "permision_key": "string",
    "permission_name": "string",
    "permission_desc": "string"
  }
]

404 Not Found - Role not found

{
  "detail": "Role not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get User Roles

GET /role/user/{user_id}

Retrieves the roles assigned to a user. Requires the view_roles permission.

Path Parameters

user_id (UUID): ID of the user

Responses

200 OK - Roles retrieved successfully

[
  {
    "role_id": "uuid",
    "role_name": "string",
    "role_description": "string",
    "role_is_active": true,
    "assignment_is_active": true
  }
]

404 Not Found - User not found

{
  "detail": "User not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get Role Users

GET /role/{role_id}/users

Retrieves the users assigned to a role. Requires the view_roles permission.

Path Parameters

role_id (UUID): ID of the role

Responses

200 OK - Users retrieved successfully

[
  {
    "user_id": "uuid",
    "user_code": "string",
    "user_fullname": "string",
    "user_email": "string",
    "assignment_is_active": true
  }
]

404 Not Found - Role not found

{
  "detail": "Role not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Role Structure

Roles in the UBU Digital Finance Solution have the following structure:

Role Name

The role name is a human-readable name for the role, such as:

"Super Admin"
"Branch Manager"
"Teller"
"Customer"

Role Description

The role description provides additional context about what the role represents, such as:

"Administrator with full system access"
"Manager of a branch office with oversight capabilities"
"Front-line staff handling customer transactions"
"End user of the system with limited access"

Role Status

Roles can be active or inactive:

Active roles can be assigned to users
Inactive roles cannot be assigned to users
Existing assignments to inactive roles are not automatically removed

Default Roles

The system includes a set of default roles:

Role Name	Description	Permissions
Super Admin	Administrator with full system access	All permissions
Branch Manager	Manager of a branch office	User management, view data, approve transactions
Teller	Front-line staff	Basic user operations, process transactions
Customer	End user of the system	View own profile, perform basic operations

Role Assignment

Roles are assigned to users through the User API when creating or updating a user. The assignment includes:

User ID: The ID of the user
Role ID: The ID of the role
Active Status: Whether the role assignment is active

A user can have multiple roles, but typically one primary role is used for most operations.

Role-Based Access Control

The system implements role-based access control (RBAC) through the permission system:

Permissions are assigned to roles
Roles are assigned to users
When a user attempts to access a protected resource, the system checks if the user has the required permission through their assigned roles

This provides a flexible and maintainable approach to access control.