Create Permission Create a new permission in the system.
Endpoint Authorization Requires Administrator role.
Request Body Unique name of the permission (e.g., “users.create”, “reports.view”)
Human-readable description of what the permission allows
Module or feature area this permission belongs to (e.g., “Users”, “Reports”)
Response HTTP status code: 201 Created
The ID of the newly created permission
Location header with URL to the created permission: /api/permissions/{id}
Example Request curl -X POST https://api.sapfiai.com/api/Permissions \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "users.create", "description": "Allows creating new users in the system", "module": "Users" }'
Example Response Update Permission Update an existing permission’s properties.
Endpoint PUT /api/Permissions/{permissionId}
Authorization Requires Administrator role.
Path Parameters ID of the permission to update
Request Body ID of the permission (must match path parameter)
Description of the permission
Module the permission belongs to
Whether the permission is active
Response HTTP status code: 204 No Content on success
Example Request curl -X PUT https://api.sapfiai.com/api/Permissions/42 \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "permissionId": 42, "name": "users.create", "description": "Allows creating and inviting new users", "module": "Users", "isActive": true }'
Delete Permission Delete a permission from the system.
Deleting a permission will remove it from all roles. This action cannot be undone.
Endpoint DELETE /api/Permissions/{permissionId}
Authorization Requires Administrator role.
Path Parameters ID of the permission to delete
Response HTTP status code: 204 No Content on success
Example Request curl -X DELETE https://api.sapfiai.com/api/Permissions/42 \ -H "Authorization: Bearer YOUR_TOKEN"
Get All Permissions Retrieve a list of all permissions in the system.
Endpoint Authorization Requires Administrator role.
Query Parameters When set to true, returns only active permissions
Response Array of permission objects Whether the permission is active
Example Request # Get all permissions curl -X GET https://api.sapfiai.com/api/Permissions \ -H "Authorization: Bearer YOUR_TOKEN" # Get only active permissions curl -X GET "https://api.sapfiai.com/api/Permissions?activeOnly=true" \ -H "Authorization: Bearer YOUR_TOKEN"
Example Response [ { "id" : 1 , "name" : "users.create" , "description" : "Allows creating new users in the system" , "module" : "Users" , "isActive" : true , "createdAt" : "2024-01-15T10:30:00Z" }, { "id" : 2 , "name" : "users.read" , "description" : "Allows viewing user information" , "module" : "Users" , "isActive" : true , "createdAt" : "2024-01-15T10:31:00Z" }, { "id" : 3 , "name" : "reports.export" , "description" : "Allows exporting reports to various formats" , "module" : "Reports" , "isActive" : true , "createdAt" : "2024-01-15T10:32:00Z" } ]
Get Permission by ID Retrieve details of a specific permission.
Endpoint GET /api/Permissions/{permissionId}
Authorization Requires Administrator role.
Path Parameters ID of the permission to retrieve
Response Whether the permission is active
Example Request curl -X GET https://api.sapfiai.com/api/Permissions/1 \ -H "Authorization: Bearer YOUR_TOKEN"
Example Response { "id" : 1 , "name" : "users.create" , "description" : "Allows creating new users in the system" , "module" : "Users" , "isActive" : true , "createdAt" : "2024-01-15T10:30:00Z" }
Assign Permission to Role Assign a permission to a specific role.
Endpoint POST /api/Permissions/assign
Authorization Requires Administrator role.
Request Body ID of the role to assign the permission to
ID of the permission to assign
User ID of the administrator making the assignment (optional)
Response HTTP status code: 204 No Content on success
Example Request curl -X POST https://api.sapfiai.com/api/Permissions/assign \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "roleId": "550e8400-e29b-41d4-a716-446655440000", "permissionId": 1, "assignedBy": "auth0|admin123" }'
Remove Permission from Role Remove a permission assignment from a role.
Endpoint POST /api/Permissions/remove
Authorization Requires Administrator role.
Request Body ID of the role to remove the permission from
ID of the permission to remove
Response HTTP status code: 204 No Content on success
Example Request curl -X POST https://api.sapfiai.com/api/Permissions/remove \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "roleId": "550e8400-e29b-41d4-a716-446655440000", "permissionId": 1 }'
Get Role Permissions Retrieve all permissions assigned to a specific role.
Endpoint GET /api/Permissions/role/{roleId}
Authorization Requires Administrator role.
Path Parameters ID of the role to retrieve permissions for
Response Array of permission objects assigned to the role
Example Request curl -X GET https://api.sapfiai.com/api/Permissions/role/550e8400-e29b-41d4-a716-446655440000 \ -H "Authorization: Bearer YOUR_TOKEN"
Example Response [ { "id" : 1 , "name" : "users.create" , "description" : "Allows creating new users in the system" , "module" : "Users" , "isActive" : true , "createdAt" : "2024-01-15T10:30:00Z" }, { "id" : 2 , "name" : "users.read" , "description" : "Allows viewing user information" , "module" : "Users" , "isActive" : true , "createdAt" : "2024-01-15T10:31:00Z" } ]
Common Workflows Setup Role with Full Module Access // Create permissions for a module var modulePermissions = new [] { new { Name = "documents.create" , Description = "Create documents" , Module = "Documents" }, new { Name = "documents.read" , Description = "View documents" , Module = "Documents" }, new { Name = "documents.update" , Description = "Update documents" , Module = "Documents" }, new { Name = "documents.delete" , Description = "Delete documents" , Module = "Documents" } }; var permissionIds = new List < int >(); // Create each permission foreach ( var perm in modulePermissions ) { var content = new StringContent ( JsonSerializer . Serialize ( perm ), Encoding . UTF8 , "application/json" ); var response = await client . PostAsync ( "https://api.sapfiai.com/api/Permissions" , content ); var permId = int . Parse ( await response . Content . ReadAsStringAsync ()); permissionIds . Add ( permId ); } // Assign all permissions to a role var roleId = "550e8400-e29b-41d4-a716-446655440000" ; foreach ( var permId in permissionIds ) { var assignCommand = new { RoleId = roleId , PermissionId = permId }; await client . PostAsync ( "https://api.sapfiai.com/api/Permissions/assign" , new StringContent ( JsonSerializer . Serialize ( assignCommand ), Encoding . UTF8 , "application/json" ) ); }
Error Responses Bad Request - Invalid request parameters or permission already exists { "errors" : { "Name" : [ "Permission name already exists" ], "Module" : [ "Module is required" ] } }
Not Found - Permission or role not found
Conflict - Permission already assigned to role (for assign) or not assigned (for remove)