Custom Roles

Production - RoleService - custom role creation with fine-grained permissions

Custom roles allow tenant administrators to create application-specific roles with precisely tailored permission sets. Unlike system roles, custom roles can be freely modified and deleted.

6.5.4Creating a Custom Role

Step 1: Create the Role

curl -X POST http://localhost:8081/api/v1/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "bi-developer",
    "description": "Business intelligence developer with dashboard and query access"
  }'

Step 2: Assign Permissions

curl -X POST http://localhost:8081/api/v1/roles/10/permissions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '[5, 8, 12, 15]'

Step 3: Assign to Users

curl -X PUT http://localhost:8081/api/v1/users/42/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '[1, 10]'

6.5.5System vs Custom Roles

Aspect	System Role	Custom Role
`system` flag	`true`	`false`
Modifiable	No	Yes
Deletable	No	Yes
Created by	Database migration	Tenant admin
Examples	admin, user, platform_admin	bi-developer, data-steward

Role Design Best Practices

Least privilege: Start with minimal permissions and add as needed
Role hierarchy: Use parent roles to share common permission sets
Naming conventions: Use lowercase with hyphens (e.g., data-analyst, bi-developer)
Documentation: Always include a description explaining the role's purpose
Regular review: Use the AccessReviewService for periodic access reviews

Permission Model Permission Cache