Permission API

The Permission API provides endpoints for managing permissions within the UBU Digital Finance Solution.

Endpoints

Create Permission

POST /permission/

Creates a new permission. Requires the create_permission permission.

Request Body

{
  "permision_key": "string",
  "permission_name": "string",
  "permission_desc": "string"
}

Responses

201 Created - Permission created successfully

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

400 Bad Request - Validation error

{
  "detail": "Permission with this key already exists."
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get All Permissions

GET /permission/

Retrieves a list of all permissions. Requires the view_permissions permission.

Responses

200 OK - Permissions retrieved successfully

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

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Get Permission

GET /permission/{permission_id}

Retrieves a specific permission. Requires the view_permissions permission.

Path Parameters

permission_id (UUID): ID of the permission

Responses

200 OK - Permission retrieved successfully

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

404 Not Found - Permission not found

{
  "detail": "Permission not found"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Update Permission

PUT /permission/{permission_id}

Updates a permission. Requires the update_permission permission.

Path Parameters

permission_id (UUID): ID of the permission to update

Request Body

{
  "permision_key": "string",
  "permission_name": "string",
  "permission_desc": "string"
}

Responses

200 OK - Permission updated successfully

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

404 Not Found - Permission not found

{
  "detail": "Permission not found"
}

400 Bad Request - Validation error

{
  "detail": "Permission with this key already exists."
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Delete Permission

DELETE /permission/{permission_id}

Deletes a permission. Requires the delete_permission permission.

Path Parameters

permission_id (UUID): ID of the permission to delete

Responses

200 OK - Permission deleted successfully

{
  "detail": "Permission deleted successfully"
}

404 Not Found - Permission not found

{
  "detail": "Permission not found"
}

400 Bad Request - Permission in use

{
  "detail": "Cannot delete permission as it is assigned to one or more roles"
}

403 Forbidden - Insufficient permissions

{
  "detail": "Permission denied"
}

Permission Structure

Permissions in the UBU Digital Finance Solution follow a specific structure:

Permission Key

The permission key is a unique identifier for the permission, typically following a format like:

create_user: Permission to create users
view_users: Permission to view all users
update_user: Permission to update user information
delete_user: Permission to delete users

The key should be descriptive and follow a consistent naming pattern.

Permission Name

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

"Create User"
"View Users"
"Update User"
"Delete User"

Permission Description

The permission description provides additional context about what the permission allows, such as:

"Allows creating new user accounts in the system"
"Allows viewing the list of all users in the system"
"Allows updating user information"
"Allows deleting user accounts from the system"

Default Permissions

The system includes a set of default permissions for common operations:

Permission Key	Permission Name	Description
`create_user`	Create User	Allows creating new user accounts
`view_users`	View Users	Allows viewing the list of all users
`view_user_profile`	View User Profile	Allows viewing a specific user's profile
`update_user`	Update User	Allows updating user information
`activate_deactivate_user`	Activate/Deactivate User	Allows activating or deactivating user accounts
`reset_password`	Reset Password	Allows resetting a user's password
`change_password`	Change Password	Allows changing own password
`create_permission`	Create Permission	Allows creating new permissions
`view_permissions`	View Permissions	Allows viewing all permissions
`update_permission`	Update Permission	Allows updating permissions
`delete_permission`	Delete Permission	Allows deleting permissions
`create_role`	Create Role	Allows creating new roles
`view_roles`	View Roles	Allows viewing all roles
`update_role`	Update Role	Allows updating roles
`delete_role`	Delete Role	Allows deleting roles
`assign_permissions`	Assign Permissions	Allows assigning permissions to roles
`view_role_permissions`	View Role Permissions	Allows viewing permissions assigned to a role
`create_organizational_unit`	Create Organizational Unit	Allows creating new organizational units
`view_organizational_units`	View Organizational Units	Allows viewing all organizational units
`update_organizational_unit`	Update Organizational Unit	Allows updating organizational units
`delete_organizational_unit`	Delete Organizational Unit	Allows deleting organizational units

Permission Usage

Permissions are used throughout the system to control access to various features and endpoints. They are typically assigned to roles, which are then assigned to users.

When a user attempts to access a protected resource, the system checks if the user has the required permission by:

Retrieving the user's active roles
Retrieving the permissions associated with those roles
Checking if the required permission is in the user's permission set

This check is implemented using the permission dependency in the FastAPI routes.