Access: Generic membership endpoints require Admin+ roles for mutations. Visibility depends on member_uuid or resource_owner status. See access-control.md.

Manages the lifecycle of relationships between entities and resources (Organisations, Assets, Airspace Zones). This unified API replaces domain-specific “Memberships”, “Transfers”, and “Invitations”.

Data Models: Resource Invitation, Resource Membership

Enums: resource_type, member_type, resource_invitation_status, resource_membership_status

Resource Memberships Summary

Create Resource Invitation

POST /resource-invitations

Initiate a new relationship. This can be an invitation to a User or an ownership transfer request to another Organisation.

Request Body (User to Org)

{
  "resource_type": 1, // Organisation
  "resource_uuid": "...", // Org UUID
  "invitee_type": 1, // User
  "invite_mode": 1, // email
  "invite_identifier": "alice@example.com",
  "invite_role": 3 // Member role
}

Request Body (Asset Transfer)

{
  "resource_type": 2, // Asset
  "resource_uuid": "...", // Asset UUID
  "invitee_type": 2, // Organisation
  "invitee_uuid": "...", // Target Org UUID
  "invite_role": 1 // Owner role
}

For the generic resource-invitations endpoint, asset transfers use invitee_type: 2 and invitee_uuid for the destination organisation UUID. When the frontend has the human-readable organisation identifier, use POST /assets/\{asset_uuid\}/transfers with org_udai_id; that endpoint resolves the organisation UUID while keeping the asset owner as an organisation. invite_identifier is not used for this transfer flow.

Process Invitation

POST /resource-invitations/accept

Accept or decline a pending transaction using the secure token or invitation UUID.

Request Body:

{
  "invite_token": "a12b34...", // Or invite_uuid
  "accept": true
}

Acceptance Logic:

• Inbound Invitation: Send by Owner $\rightarrow$ Guest. Guest calls /accept.
• Outbound Request: Send by Guest $\rightarrow$ Owner. Owner calls /accept.

The backend determines permission based on invited_by_user_uuid. If the initiator is the resource_owner admin, it’s an invite. Otherwise, it’s a request.

For asset transfers through the asset shortcut, the accepting user must be an Admin or Owner of the destination organisation and must send that organisation’s X-Organisation-ID. The invitation’s invitee_uuid still determines the transfer target. Generic invitation acceptance remains context-independent for invitation flows that do not use the asset shortcut.

Side-effects & Field Synchronization: Upon acceptance, the following relational updates are mandatory:

1. Primary Record Creation: A new entry in Resource Memberships table.
2. Ownership Update (Exclusive Resources):
   • Assets: The org_owner_uuid in the Assets table MUST be updated to the destination organisation’s UUID.
   • Airspace Zones: If the role is Owner, the org_owner_uuid in the Airspace Zones table must be updated.
3. Previous Record Cleanup: For exclusive resources (Assets/Org Ownership), any previous Active membership for that resource must be marked REMOVED (-2).

List Memberships

GET /resource-memberships

Returns a consolidated list of resources the requester is linked to.

Query Parameters:

• resource_type: Filter by type (Org, Asset, Zone).
• member_uuid: Filter by specific member (e.g., “Show all assets owned by Org X”).
• status: Filter by resource_membership_status.

Example Response (Asset Ownership):

{
  "data": [
    {
      "membership_uuid": "...",
      "resource_type": 2,
      "resource_uuid": "...",
      "resource_name": "SkyRanger X1",
      "member_type": 2,
      "member_uuid": "...",
      "role": 1,
      "status": 1
    }
  ]
}

Remove Membership

DELETE /resource-memberships/{membership_uuid}

Ends an active relationship.

• For Users: Removes them from the organisation.
• For Assets: Effectively “deregisters” the owner or initiates a return.
• For Airspace: Revokes the organisation’s management/monitoring rights.