Permission Management API Reference

Identity domain API for managing tenant permissions and role-based access control

Base InformationCopy Anchor Link

Endpoints OverviewCopy Anchor Link

Important: How Permissions WorkCopy Anchor Link

The system uses a cascading permission model:

1. System Defaults (GET /permissions): All available permissions with their default role assignments
2. Tenant Overrides (GET /tenants/:tenant_id/permissions): Custom permissions set by the tenant

Frontend Usage Pattern: To show effective permissions in the UI:

1. Call GET /permissions to get all available permissions with defaults
2. Call GET /tenants/:tenant_id/permissions to get tenant overrides
3. Merge them: if a permission has an override, use it; otherwise use the system default

1. List System PermissionsCopy Anchor Link

Get all available system permissions with their default role assignments. Used to show the UI a list of all possible permissions.

RequestCopy Anchor Link

GET /api/v1/identity/permissions

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

curl -X GET "https://api.example.com/api/v1/identity/permissions?display=true" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Response (200 OK)Copy Anchor Link

{
  "data": [
    {
      "id": "019c6f7d-0b4c-7d62-8952-d788061ca293",
      "created_at": "2026-02-18T06:43:11Z",
      "updated_at": "2026-02-18T06:43:11Z",
      "feature_name": "manage_appointments",
      "feature_category": "appointments",
      "access_level": "manage",
      "display": true,
      "default_enabled_for_roles": ["owner", "admin", "staff"]
    },
    {
      "id": "019c6f7d-0b40-76a1-9ecd-643a57b5a71a",
      "created_at": "2026-02-18T06:43:11Z",
      "updated_at": "2026-02-18T06:43:11Z",
      "feature_name": "view_patients",
      "feature_category": "clinical",
      "access_level": "view",
      "display": true,
      "default_enabled_for_roles": ["owner", "admin", "staff", "practitioner"]
    }
  ],
  "meta": {
    "request_id": "f75d3cc5-b994-4fdd-83a2-ba8206207acb"
  }
}

Response FieldsCopy Anchor Link

feature_category changed meaning, and kept its name (#2421). It used to hold a loose grouping: appointments, patients, medical_records, billing, reports, settings, care_plans, packages, audit_trail, ai, growth, and four values no key ever used. It now holds an AREA, which is the unit an owner sets access by: one of clinical, appointments, patient_billing, marketing, my_earnings, practice_finance, revenue_share, payouts, tax_identity, team_settings, subscription.

The field name did not change, so a consumer that matches on the old values keeps parsing the response and silently matches nothing. The value set is the breaking part. billing is the one to look at first: it split into patient_billing (the patient's bill at the front desk) and practice_finance (the practice's own money), which are unrelated subjects that shared a name.

Read the area from this field and the level from access_level. Do not derive either from the key name.

2. List Tenant Permission OverridesCopy Anchor Link

Get tenant-specific permission customizations (overrides). Note: This only returns permissions that have been customized by the tenant. If no overrides exist, returns an empty array.

RequestCopy Anchor Link

GET /api/v1/identity/tenants/:tenant_id/permissions

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

curl -X GET "https://api.example.com/api/v1/identity/tenants/550e8400-e29b-41d4-a716-446655440000/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json"

Response (200 OK)Copy Anchor Link

{
  "data": [
    {
      "role": "owner",
      "permissions": [
        {
          "id": "tenant-permission-uuid",
          "permission_id": "019c6f7d-0b4c-7d62-8952-d788061ca293",
          "permission_name": "manage_appointments",
          "permission_category": "appointments",
          "enabled": true,
          "is_custom": true,
          "default_for_roles": ["owner", "admin", "staff"]
        }
      ]
    },
    {
      "role": "admin",
      "permissions": [
        {
          "id": "tenant-permission-uuid",
          "permission_id": "019c6f7d-0b40-76a1-9ecd-643a57b5a71a",
          "permission_name": "view_patients",
          "permission_category": "patients",
          "enabled": true,
          "is_custom": true,
          "default_for_roles": ["owner", "admin", "staff", "practitioner"]
        }
      ]
    }
  ],
  "meta": {
    "request_id": "f75d3cc5-b994-4fdd-83a2-ba8206207acb"
  }
}

Response FieldsCopy Anchor Link

Empty Response (No Overrides)Copy Anchor Link

{
  "data": [],
  "meta": {
    "request_id": "f75d3cc5-b994-4fdd-83a2-ba8206207acb"
  }
}

3. Update Tenant PermissionsCopy Anchor Link

Update which permissions are enabled for a specific role. This is a sync operation - it replaces all existing permissions for that role with the new list.

RequestCopy Anchor Link

PUT /api/v1/identity/tenants/:tenant_id/permissions

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

curl -X PUT "https://api.example.com/api/v1/identity/tenants/550e8400-e29b-41d4-a716-446655440000/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "staff",
    "permission_ids": [
      "019c6f7d-0b4c-7d62-8952-d788061ca293",
      "019c6f7d-0b40-76a1-9ecd-643a57b5a71a"
    ]
  }'

Response (200 OK)Copy Anchor Link

{
  "data": {
    "message": "Permissions updated successfully"
  },
  "meta": {
    "request_id": "f75d3cc5-b994-4fdd-83a2-ba8206207acb"
  }
}

Error ResponsesCopy Anchor Link

An owner-only area belongs to one named person, so no role may hold it. The areas are subscription, payouts and tax_identity. The server refuses the WHOLE request and writes nothing, so a request that mixes one owner-only key with valid keys saves none of them. The owner gets the same refusal: the rule is about what a ROLE may hold, not about who asks.

Error Example (422, owner-only area)Copy Anchor Link

{
  "data": null,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "payouts belongs to the owner alone and cannot be given to a role",
    "details": [
      { "field": null, "message": "payouts belongs to the owner alone and cannot be given to a role" }
    ]
  },
  "meta": {
    "request_id": "f75d3cc5-b994-4fdd-83a2-ba8206207acb"
  }
}

Error Example (403)Copy Anchor Link

{
  "data": null,
  "error": {
    "code": "forbidden",
    "message": "You are not authorized to perform this action",
    "details": [
      { "field": "policy", "message": "Identity::TenantPermissionPolicy" },
      { "field": "query", "message": "index?" }
    ]
  },
  "meta": {
    "request_id": "f75d3cc5-b994-4fdd-83a2-ba8206207acb"
  }
}

Error Example (404)Copy Anchor Link

{
  "data": null,
  "error": {
    "code": "TENANT_NOT_FOUND",
    "message": "Tenant not found",
    "details": [
      { "field": "resource_type", "message": "Tenant" },
      { "field": "id", "message": "550e8400-e29b-41d4-a716-446655440000" }
    ]
  },
  "meta": {
    "request_id": "f75d3cc5-b994-4fdd-83a2-ba8206207acb"
  }
}

Complete Permission ReferenceCopy Anchor Link

All 27 available permissions in the system with their IDs:

AppointmentsCopy Anchor Link

BillingCopy Anchor Link

Billing is three separate families, not one (#2277, #2274). manage_practice_finance used to gate all three, so granting someone the ability to settle a payout also let them raise a patient bill and cancel the Kulcare subscription. Pick the family by asking whose money is this — the patient's, the practice's, or Kulcare's. See Billing domain architecture.

Patient bills — the front desk's and the clinician's work.

Practice finance — commissions, revenue share, payouts, P&L.

Kulcare subscription — the tenant's own plan, subscription invoices, payment methods and module add-ons. Deliberately narrower than the other two: owner only. An admin who should be able to change the plan is granted it at the role level, per tenant. has_permission? short-circuits on role_owner?, so an owner holds these with no row at all.

The ID columns elsewhere in this document are environment-specific — reference.permissions ids are generated per database, so the values listed will not match your environment. Match on feature_name, which is unique and stable; the seed at backend/db/seeds/reference/015_seed_permissions.rb is the source of truth for the default roles above.

Care PlansCopy Anchor Link

PatientsCopy Anchor Link

ReportsCopy Anchor Link

SettingsCopy Anchor Link

RolesCopy Anchor Link

AuthorizationCopy Anchor Link

Required PermissionsCopy Anchor Link

Other members get 403 from both endpoints. Each user gets their own permissions from GET /identity/my/permissions.

The tenant_id in the URL must be the session's tenant. Any other id gets 404, before the policy runs, on every route under /tenants/:tenant_id/permissions (including /access). This holds for an owner of another tenant too, and the answer is the same as for an id that does not exist, so the endpoint does not confirm that another tenant exists. The id is compared ignoring case, and only in the canonical hyphenated form. The refusal writes no audit record, so the attempt does not reach the other tenant's activity log (#2351).

Policy RulesCopy Anchor Link

# identity/policies/tenant_permission_policy.rb
def index?
  in_this_tenant? && tenant_admin?   # tenant_admin? is true for owners too
end

def update?
  in_this_tenant? && tenant_owner?
end

def update_role?(role)
  update? && role.to_s != 'owner'
end

Only the owner can save, because a person who can save can give a role manage_subscription and so let that role cancel the Kulcare plan. SyncTenantPermissions repeats the same rules.

Complete Usage ExampleCopy Anchor Link

Step 1: Get all available permissionsCopy Anchor Link

GET /api/v1/identity/permissions

Returns all system permissions with their default roles.

Step 2: Get tenant overridesCopy Anchor Link

GET /api/v1/identity/tenants/:tenant_id/permissions

Returns only customized permissions (may be empty if no customization).

Step 3: Calculate effective permissionsCopy Anchor Link

On the frontend, merge the two responses:

// Pseudocode
const systemPermissions = systemResponse.data;
const tenantOverrides = tenantResponse.data;

// Build override map
const overrideMap = new Map();
tenantOverrides.forEach(roleGroup => {
  roleGroup.permissions.forEach(perm => {
    overrideMap.set(perm.permission_id, perm.enabled);
  });
});

// Calculate effective permissions
const effectivePermissions = systemPermissions.map(perm => {
  const override = overrideMap.get(perm.id);
  return {
    ...perm,
    enabled: override !== undefined ? override :
      perm.default_enabled_for_roles.includes(userRole)
  };
});

Step 4: Update permissionsCopy Anchor Link

PUT /api/v1/identity/tenants/:tenant_id/permissions
{
  "role": "staff",
  "permission_ids": ["uuid1", "uuid2", "uuid3"]
}

Response Format SummaryCopy Anchor Link

Success ResponseCopy Anchor Link

{
  "data": { ... },
  "meta": {
    "request_id": "uuid"
  }
}

Error ResponseCopy Anchor Link

{
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "The first error message",
    "details": [{ "field": null, "message": "The first error message" }]
  },
  "meta": {
    "request_id": "uuid"
  }
}