Roles & Permissions Postman Doc: https://documenter.getpostman.com/view/20499442/[merchant-collection-id] -------------------------------------------------------------------------------- API: Create Role -------------------------------------------------------------------------------- POST /merchant/api/v1/domains/:domain_id/roles [Seller Admin, Orchestration] Description: Create a new role with named permissions for domain-level access control. Request Body: { "name": "Order Manager", "description": "Manages customer orders, including processing and returns", "permissions": [ "view_orders", "add_order", "edit_order", "delete_order", "view_customers" ] } Response: 201 Created { "id": "67af23c651096329b404e0c3", "name": "Order Manager", "description": "Manages customer orders...", "domain_id": "674d6a93c69a4d6a98c8d464", "permissions": ["view_orders", "add_order", ...], "created_at": "2025-02-14T11:06:46.103Z", "updated_at": "2025-02-14T11:06:46.103Z" } Flow Sequence: # Step 1: Validate Token at Gateway Level (JWT validation) # Step 2: Create Role Record POST /api/roles [User Service, Core Microservices] # Step 3: Audit and Cache Invalidation POST /api/events/log [Util Service] POST /api/cache/invalidate [Caching Service] -------------------------------------------------------------------------------- API: List Roles -------------------------------------------------------------------------------- GET /merchant/api/v1/domains/:domain_id/roles [Seller Admin, Orchestration] Description: Retrieve all roles for the given domain. Response: 200 OK [ { "id": "67af23c651096329b404e0c3", "name": "Order Manager", "description": "...", "domain_id": "674d6a93c69a4d6a98c8d464", "permissions": ["view_orders", ...], "created_at": "2025-02-14T11:06:46.103Z", "updated_at": "2025-02-14T11:06:46.103Z" } ] Flow Sequence: # Step 1: Validate Token at Gateway Level (JWT validation) # Step 2: Fetch Roles GET /api/roles?domain_id=:domain_id [User Service, Core Microservices] -------------------------------------------------------------------------------- API: Get Role -------------------------------------------------------------------------------- GET /merchant/api/v1/domains/:domain_id/roles/:role_id [Seller Admin, Orchestration] Description: Retrieve a specific role by ID. Response: 200 OK with role object Flow Sequence: # Step 1: Validate Token at Gateway Level (JWT validation) # Step 2: Fetch Role GET /api/roles/:role_id [User Service, Core Microservices] -------------------------------------------------------------------------------- API: Update Role -------------------------------------------------------------------------------- PUT /merchant/api/v1/domains/:domain_id/roles/:role_id [Seller Admin, Orchestration] Description: Update role name, description, and permissions. Request Body: { "name": "Order Manager", "description": "Updated description", "permissions": [ "view_orders", "add_order", "edit_order", "delete_order", "view_customers" ] } Response: 200 OK with updated role object Error Response (400): { "error": { "status": 400, "message": "Invalid permissions when updating role" } } Flow Sequence: # Step 1: Validate Token at Gateway Level (JWT validation) # Step 2: Validate Permissions (must be valid permission keys) # Step 3: Update Role Record PUT /api/roles/:role_id [User Service, Core Microservices] # Step 4: Audit and Cache Invalidation POST /api/events/log [Util Service] POST /api/cache/invalidate [Caching Service] # Step 5: Notify session service to refresh permissions POST /api/sessions/refresh-permissions [User Service] -------------------------------------------------------------------------------- API: Delete Role -------------------------------------------------------------------------------- DELETE /merchant/api/v1/domains/:domain_id/roles/:role_id [Seller Admin, Orchestration] Description: Delete a role from the domain. Response: 204 No Content Flow Sequence: # Step 1: Validate Token at Gateway Level (JWT validation) # Step 2: Delete Role Record DELETE /api/roles/:role_id [User Service, Core Microservices] # Step 3: Audit and Cache Invalidation POST /api/events/log [Util Service] POST /api/cache/invalidate [Caching Service] -------------------------------------------------------------------------------- API: List Permissions -------------------------------------------------------------------------------- GET /merchant/api/v1/permissions [Seller Admin, Orchestration] Description: Retrieve all available permissions that can be assigned to roles. This endpoint is NOT domain-scoped. Response: 200 OK [ "view_general_settings", "add_general_settings", "edit_general_settings", "view_orders", "add_order", "edit_order", "delete_order", "view_products", "add_products", "edit_products", "delete_products", "view_customers", "add_customers", "edit_customers", "delete_customers", "view_staff", "add_staff", "edit_staff", "delete_staff", "view_roles", "add_roles", "edit_roles", "delete_roles", ... (150+ permission keys) ] Flow Sequence: # Step 1: Validate Token at Gateway Level (JWT validation) # Step 2: Fetch Permission List GET /api/permissions [User Service, Core Microservices] Notes: - Token validation happens at the Seller API Gateway level (JWT validation) - Roles are domain-scoped; each domain has its own set of roles - Permissions are system-wide constants, not domain-specific - Role changes should trigger session refresh to avoid privilege drift - Invalid permissions in create/update will return 400 error Permission Categories: - Store Settings: view_general_settings, edit_general_settings, etc. - Orders: view_orders, add_order, edit_order, delete_order - Products: view_products, add_products, edit_products, delete_products - Customers: view_customers, add_customers, edit_customers, delete_customers - Staff: view_staff, add_staff, edit_staff, delete_staff - Roles: view_roles, add_roles, edit_roles, delete_roles - Categories: view_categories, add_categories, edit_categories, delete_categories - Coupons: view_coupons, add_coupons, edit_coupons, delete_coupons - Themes: view_theme, add_theme, edit_theme, delete_theme - Pages: view_pages, add_pages, edit_pages, delete_pages - Blogs: view_blogs, add_blogs, edit_blogs, delete_blogs