Clinic Permissions API Integration Guide

This document provides a comprehensive guide for frontend developers to integrate the Clinic Permissions APIs into the Kulcare application.

Table of ContentsCopy Anchor Link

• Overview
• Database Schema
• System Architecture
• API Endpoints
• Permission Management Flow
• Permission Search via Elasticsearch
• Response Formats
• Error Handling

OverviewCopy Anchor Link

The Clinic Permissions system allows clinic owners and administrators to manage role-based permissions for their clinic staff. This granular permission system ensures that staff members only have access to features they need for their specific roles.

Key Features:Copy Anchor Link

• Role-based permissions: Assign permissions to specific roles (Owner, Doctor, Receptionist, Admin)
• Granular control: Control access to individual features across all modules
• Default permissions: Each role comes with predefined default permissions
• Elasticsearch integration: Fast permission search and filtering capabilities

Permission Categories:Copy Anchor Link

• Appointments
• Patients
• Billing
• Settings
• Communications
• Packages
• Account

Database SchemaCopy Anchor Link

The RBAC system is built on three core tables that work together to provide flexible, clinic-specific permission management:

System ArchitectureCopy Anchor Link

The following diagram shows how the RBAC system components interact:

Required Permissions for API EndpointsCopy Anchor Link

Each API endpoint in the Kulcare system requires specific permissions. Below are the key permission requirements:

✅ APIs Updated with RBAC in This PRCopy Anchor Link

The following endpoints have been updated to use the new RBAC permission system:

Appointments ModuleCopy Anchor Link

• GET /clinics/:clinic_id/appointments (index): Requires appointments.view permission
• GET /clinics/:clinic_id/appointments/list (list): Requires appointments.view permission
• POST /clinics/:clinic_id/appointments (create): Requires appointments.create permission
• PUT /clinics/:clinic_id/appointments/:id (update): Requires appointments.edit/appointments.reschedule permission
• DELETE /clinics/:clinic_id/appointments/:id (destroy): Requires appointments.delete permission

Patients ModuleCopy Anchor Link

• GET /clinics/:clinic_id/patients (index): Requires patients.view_list permission
• GET /clinics/:clinic_id/patients/list (list): Requires patients.view_list OR billing.reports permission
• GET /clinics/:clinic_id/patients/:id (show): Requires patients.view_details permission
• POST /clinics/:clinic_id/patients (create): Requires patients.create OR patients.edit permission
• GET /clinics/:clinic_id/patients/generate_report (generate_report): Requires patients.view_list OR billing.reports permission

Billing ModuleCopy Anchor Link

• GET /clinics/:clinic_id/bills/today (todays_bills): Requires billing.view permission
• POST /clinics/:clinic_id/bills (create): Requires billing.create permission
• PUT /clinics/:clinic_id/bills/:id (update): Requires billing.edit permission
• DELETE /clinics/:clinic_id/bills/:id (destroy): Requires billing.edit permission
• GET /clinics/:clinic_id/clinic_bills (index): Requires billing.reports permission
• GET /clinics/:clinic_id/clinic_bills/summary (summary): Requires billing.reports permission
• GET /clinics/:clinic_id/billing_logs (billing_logs): Requires billing.reports permission

Care Packages ModuleCopy Anchor Link

• GET /clinics/:clinic_id/packages (index): Requires packages.view permission
• GET /clinics/:clinic_id/packages/:id (show): Requires packages.view permission
• POST /clinics/:clinic_id/packages (create): Requires packages.create permission
• DELETE /clinics/:clinic_id/packages/:id (destroy): Requires packages.delete permission
• POST /clinics/:clinic_id/packages/:id/associate (associate): Requires packages.view permission
• POST /clinics/:clinic_id/packages/:id/share (share): Requires packages.share permission

Settings ModuleCopy Anchor Link

• GET /clinics/:clinic_id/settings (show): Requires settings.clinic permission
• GET /clinics/:clinic_id/services (index): Requires settings.clinic permission
• POST /clinics/:clinic_id/services (create): Requires settings.clinic permission
• GET /clinics/:clinic_id/staff (index): Requires settings.users permission
• POST /clinics/:clinic_id/staff (create): Requires settings.users permission
• DELETE /clinics/:clinic_id/staff/:id (destroy): Requires settings.users permission
• POST /clinics/:clinic_id/staff/:id/reinvite (reinvite): Requires settings.users permission
• GET /clinics/:clinic_id/permissions (index): Requires settings.permissions.view permission
• POST /clinics/:clinic_id/permissions (create): Requires settings.permissions.edit permission
• POST /clinics/:clinic_id/permissions/remove (remove): Requires settings.permissions.edit permission

Communications ModuleCopy Anchor Link

• POST /clinics/:clinic_id/communications/sms (sms): Requires communications permission
• POST /clinics/:clinic_id/communications/whatsapp (whatsapp): Requires communications permission
• POST /clinics/:clinic_id/communications/email (email): Requires communications permission

Account ModuleCopy Anchor Link

• GET /billing_payments (index): Requires account.transactions permission
• GET /telemedicine_payments (index): Requires account.transactions permission
• GET /clinics/:clinic_id/bank_details (index): Requires account.bank_details permission
• POST /clinics/:clinic_id/bank_details (create): Requires account.bank_details permission

API EndpointsCopy Anchor Link

Base URL: {{url}}/clinics/:clinic_id/permissions

Permission Search API (Elasticsearch)Copy Anchor Link

Base URL: {{elasticsearch_url}}/permissions_{{env}}/_search

This endpoint provides fast search capabilities across all available permissions with filtering options.

Permission Management FlowCopy Anchor Link

1. List Current Clinic PermissionsCopy Anchor Link

Retrieve all permissions configured for the clinic, grouped by role.

GET {{url}}/clinics/:clinic_id/permissions
Authorization: Bearer {{auth_token}}

Parameters:

• clinic_id (path): The ID of the clinic

Response example:

{
  "success": true,
  "message": "Permissions fetched successfully",
  "data": [
    {
      "role_id": 1,
      "role_name": "Owner",
      "permissions": [
        {
          "id": 123,
          "permission_id": 1,
          "permission_name": "appointments.view",
          "permission_category": "appointments",
          "enabled": true,
          "created_at": "2025-01-15T10:30:00.000Z",
          "updated_at": "2025-01-15T10:30:00.000Z"
        },
        {
          "id": 124,
          "permission_id": 2,
          "permission_name": "appointments.create",
          "permission_category": "appointments",
          "enabled": true,
          "created_at": "2025-01-15T10:30:00.000Z",
          "updated_at": "2025-01-15T10:30:00.000Z"
        }
      ]
    },
    {
      "role_id": 2,
      "role_name": "Doctor",
      "permissions": [
        {
          "id": 125,
          "permission_id": 1,
          "permission_name": "appointments.view",
          "permission_category": "appointments",
          "enabled": true,
          "created_at": "2025-01-15T10:30:00.000Z",
          "updated_at": "2025-01-15T10:30:00.000Z"
        }
      ]
    }
  ]
}

UI Implementation:

• Display permissions grouped by role in a tabbed or accordion interface
• Show permission categories with expandable sections
• Use toggle switches for enable/disable functionality
• Highlight permissions that differ from defaults

2. Create/Update PermissionsCopy Anchor Link

Assign permissions to a specific role within the clinic. This endpoint can be used to:

• Grant new permissions to a role
• Update existing permission settings
• Bulk update multiple permissions at once

POST {{url}}/clinics/:clinic_id/permissions
Authorization: Bearer {{auth_token}}
Content-Type: application/json

{
  "role_id": 2,
  "permission_ids": [1, 2, 3, 5, 8]
}

Parameters:

• clinic_id (path): The ID of the clinic
• role_id (body): The role to assign permissions to
• permission_ids (body): Array of permission IDs to enable for this role

Response example:

{
  "success": true,
  "message": "Permissions updated successfully",
  "data": [
    {
      "role_id": 2,
      "role_name": "Doctor",
      "permissions": [
        {
          "id": 125,
          "permission_id": 1,
          "permission_name": "appointments.view",
          "permission_category": "appointments",
          "enabled": true,
          "created_at": "2025-01-15T10:30:00.000Z",
          "updated_at": "2025-01-15T12:00:00.000Z"
        },
        {
          "id": 126,
          "permission_id": 2,
          "permission_name": "appointments.create",
          "permission_category": "appointments",
          "enabled": true,
          "created_at": "2025-01-15T12:00:00.000Z",
          "updated_at": "2025-01-15T12:00:00.000Z"
        }
      ]
    }
  ]
}

UI Implementation:

• Show loading state during update
• Display success notification
• Update UI immediately to reflect changes
• Consider implementing optimistic updates

3. Remove PermissionsCopy Anchor Link

Remove specific permissions from a role. This is useful when you need to revoke access to certain features.

POST {{url}}/clinics/:clinic_id/permissions/remove
Authorization: Bearer {{auth_token}}
Content-Type: application/json

{
  "role_id": 2,
  "permission_ids": [3, 5]
}

Parameters:

• clinic_id (path): The ID of the clinic
• role_id (body): The role to remove permissions from
• permission_ids (body): Array of permission IDs to remove

Response example:

{
  "success": true,
  "message": "Permissions removed successfully"
}

UI Implementation:

• Confirm before removing permissions
• Show warning if removing critical permissions
• Update UI to reflect removed permissions
• Consider batch operations for efficiency

Permission Search via ElasticsearchCopy Anchor Link

The permissions are indexed in Elasticsearch for fast searching and filtering. This is particularly useful for:

• Building permission selection interfaces
• Searching permissions by name or category
• Filtering available permissions

Search All PermissionsCopy Anchor Link

POST {{elasticsearch_url}}/permissions_{{env}}/_search
Content-Type: application/json

{
  "query": {
    "match_all": {}
  },
  "size": 100
}

UI Implementation:

• Use Elasticsearch for autocomplete in permission search
• Implement category filters
• Cache search results for performance
• Show permission descriptions in search results

Response FormatsCopy Anchor Link

Success Response StructureCopy Anchor Link

All successful API calls follow this format:

{
  "success": true,
  "message": "Operation completed successfully",
  "data": { ... }
}

Error Response StructureCopy Anchor Link

{
  "success": false,
  "error": "Error message",
  "error_code": "ERROR_CODE",
  "details": { ... }
}