🔐Access Control Matrix

Defines the RBAC (Role-Based Access Control) and CBAC (Context-Based Access Control) rules for every API group and endpoint in the UDAI system.

For the full explanation of every role see enums.md — org_membership_role and org_type.

---

Global Security & Context Middleware

UDAI API access is secured and contextualized via three mandatory global middleware layers. These execute before any endpoint-specific RBAC/CBAC logic.

Middleware Layer	Header	Enforcement Logic	Exclusions
Partner Gateway	partner-api-key	Rejects requests with 401/403 if the platform API key is missing or invalid.	None
User Authentication	Authorization	Validates JWT (Bearer <token>), checks expiration/signature, and authenticates the user_uuid.	Public endpoints (e.g., /auth/register, /auth/login-password, /auth/verify/send-otp)
Delegated Context	X-Organization-ID	Enforces CBAC by parsing the org UUID and validating that the active user_uuid holds a valid membership (Owner, Admin, or Member) within that specific organization. Rejects with 403 Forbidden if the user attempts to act on behalf of an org they do not belong to.	Public endpoints and operations that resolve context implicitly (e.g., /auth/*, /users/me)

---

Key Dimensions

RBAC — Role-Based

Dimension	Values
org_membership_role	1 = Owner · 2 = Admin · 3 = Member
org_type	1 = Drone Manufacturer · 2 = Drone Owner · 3 = Airspace Manager · 4 = Airspace Monitor · 5 = RPTO · 6 = Type Certification Body · 7 = DGCA

Rule shorthand used in tables below:

• Any — any authenticated user with a valid org membership

• Member+ — org_membership_role ≥ 3

• Admin+ — org_membership_role ≥ 2

• Owner — org_membership_role = 1 only

CBAC — Context-Based

CBAC rules restrict access based on runtime context — what the requesting org or user owns or is linked to, not just their static role.

---

Access Control Matrix

1. 🔐 Authentication APIs

Group Logic: Authentication endpoints are generally Public (requiring only a Partner API Key). User and Organisation management mutations require Admin+ and are restricted to the requester's own organisation context (CBAC).

Endpoint	Method	RBAC	CBAC
/auth/login-password	POST	Public	—
/auth/login-otp	POST	Public	—
/auth/send-otp	POST	Public	—
/auth/refresh	POST	Any	—
/auth/logout	POST	Any	—
GET /users	GET	Admin+	Only within own org
GET /users/{user_uuid}	GET	Admin+	Only within own org
PUT /users/{user_uuid}/role	PUT	Admin+ (Owner only to promote to Admin)	Only within own org
GET /users/me	GET	Any	Own profile only
PUT /users/me	PUT	Any	Own profile only
GET /organisations/{org_uuid}	GET	Member+	Own org only
PUT /organisations/{org_uuid}	PUT	Admin+	Own org only
POST /invitations	POST	Admin+	Own org only
POST /invitations/accept	POST	Any	Must be the invitee
GET /invitations	GET	Admin+	Own org only
GET /invitations/{uuid}	GET	Admin+	Own org only
DELETE /memberships	DELETE	Admin+	Own org; cannot remove Owner

---

2. 🚁 Fleet APIs

Group Logic: Fleet mutations are restricted to Admin+ roles. Drone Manufacturers (Type 1) manage Drone Models, while Drone Owners (Type 2) manage physical Drones, Payloads, and Ownership transfers.

Endpoint	Method	RBAC	CBAC
POST /drone-models	POST	Admin+	org_type = Drone Manufacturer
GET /drone-models	GET	Any	—
GET /drone-models/{uuid}	GET	Any	—
PUT /drone-models/{uuid}	PUT	Admin+	org_type = Drone Manufacturer; own model only
DELETE /drone-models/{uuid}	DELETE	Admin+	org_type = Drone Manufacturer; own model only
POST /payloads	POST	Admin+	org_type = Manufacturer or Drone Owner
GET /payloads	GET	Member+	Own org's payloads only
GET /payloads/{uuid}	GET	Member+	Must own the payload
PUT /payloads/{uuid}	PUT	Admin+	Must own the payload
DELETE /payloads/{uuid}	DELETE	Admin+	Must own the payload
POST /drones	POST	Admin+	Own org only
POST /drones/bulk	POST	Admin+	Own org only
GET /drones	GET	Member+	Own org's drones only
GET /drones/{uuid}	GET	Member+	Must have active ownership of drone
PUT /drones/{uuid}	PUT	Admin+	Must have active ownership of drone
DELETE /drones/{uuid}	DELETE	Admin+	Must have active ownership of drone
POST /drone-transfer	POST	Admin+	org_type = Drone Owner; org must currently own the drone
POST /drone-transfers/accept	POST	Admin+	org_type = Drone Owner; must be the receiving org
GET /drone-transfers	GET	Member+	Own org's transfers only (as sender or receiver)
GET /drone-transfers/{uuid}	GET	Member+	Must be sender or receiver org
GET /drone-ownership	GET	Member+	Own org's ownerships only
GET /drone-ownership/{uuid}	GET	Member+	Must be the owning org
DELETE /drone-ownership/{uuid}	DELETE	Admin+	Must be the owning org; ownership must be Active

---

3. 📋 Mission APIs

Group Logic: Missions and Flight Plans are primarily managed by Drone Owners (Type 2). Creating plans requires Member+ roles. Airspace access requests are submitted by the owner and reviewed by Airspace Managers (Type 3).

Endpoint	Method	RBAC	CBAC
POST /missions	POST	Admin+	org_type = Drone Owner
GET /missions	GET	Member+	Own org only
GET /missions/{uuid}	GET	Member+	Own org only
PUT /missions/{uuid}	PUT	Admin+	Own org; created by same org
DELETE /missions/{uuid}	DELETE	Admin+	Own org only
POST .../missions/{uuid}/permissions	POST	Admin+	Own org only
PUT .../permissions/{perm_uuid}	PUT	Admin+	org_type = Airspace Manager; must have Manager membership for the zone
POST .../plans	POST	Member+	Drone and pilot must be listed in parent mission
GET .../plans	GET	Member+	Own org's plans only
GET .../plans/{uuid}	GET	Member+	Own org only
PUT .../plans/{uuid}	PUT	Member+	Must be the plan creator
POST .../plans/{uuid}/permissions	POST	Admin+	Own org only

---

4. 📊 Telemetry APIs

Group Logic: Live telemetry ingestion is restricted to the Pilot or Admin of the owning organisation. Monitoring access is restricted to Airspace Managers (Type 3) and Airspace Monitors (Type 4) for zones where they have authorized memberships.

Endpoint	Method	RBAC	CBAC
POST .../flight-sessions	POST	Member+	Must own the drone and have access to flight plan if provided
GET .../flight-sessions	GET	Member+	Own org's sessions only
GET .../flight-sessions/{uuid}	GET	Member+	Must be the pilot or org admin, or have access to the flight plan
POST .../flight-sessions/{uuid}/telemetry	POST	Member+	Must be the pilot or org admin
GET .../airspace/active-flights	GET	Member+	org_type = Airspace Manager or Airspace Monitor; zone membership required
GET .../airspace/drones/{drone_uuid}	GET	Member+	org_type = Airspace Manager or Airspace Monitor; zone membership required
GET .../airspace/drones/{drone_uuid}/plans	GET	Member+	org_type = Airspace Manager or Airspace Monitor; zone membership required
POST .../airspace/drones/{drone_uuid}/alert	POST	Admin+	org_type = Airspace Manager; zone Manager membership required

---

5. 🗺️ Airspace APIs

Group Logic: Airspace Zones and Constraints are managed by Airspace Managers (Type 3). While everyone (Any) can view zones, only authorized managers can modify geometry or memberships. The Constraint Engine acts as the geospatial backbone for all shapes.

Endpoint	Method	RBAC	CBAC
POST /airspaces	POST	Admin+	org_type = Airspace Manager
GET /airspaces	GET	Any	—
GET /airspaces/{zone_uuid}	GET	Any	—
PUT /airspaces/{zone_uuid}	PUT	Admin+	org_type = Airspace Manager; zone Manager membership required
POST /airspaces/{zone_uuid}/memberships	POST	Admin+	org_type = Airspace Manager; zone Manager membership required
GET /airspaces/{zone_uuid}/memberships	GET	Member+	Must have zone membership (Manager/Monitor)
GET /airspace-memberships	GET	Member+	Own org only
DELETE /airspaces/{zone_uuid}/memberships/{uuid}	DELETE	Admin+	org_type = Airspace Manager; zone Manager membership required
POST /constraints	POST	Internal	Restricted to platform services (Mission/Zone creation)
GET /constraints/{uuid}	GET	Any	—
POST /constraints/intersect	POST	Any	Intersection query open to all authenticated partners