@epilot/sdk 2.2.1 → 2.2.3

package/definitions/partner-directory.json

@@ -0,0 +1,2284 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Partner Directory API",
+    "description": "The Partner Directory API enables organizations to manage partnerships within the epilot platform.\n\n- **Partner Directory Management**: Maintain a directory of partner organizations that collaborate with your business\n- **Partner Invitations**: Invite external organizations to become partners through a secure token-based invitation flow\n- **Assignable Search**: Find users and organizations that can be assigned to tasks, workflows, or entities across your organization and partners\n- **Partner User Management**: Manage users within partner organizations, including creating users and assigning roles\n- **Geolocation Services**: Convert addresses to geographic coordinates for partner location-based features\n",
+    "version": "1.7.0"
+  },
+  "tags": [
+    {
+      "name": "Partners",
+      "x-displayName": "Partners",
+      "description": "Operations for managing the partner directory including:\n- Inviting new partners to collaborate\n- Approving or rejecting partner requests\n- Searching for assignable users and organizations across partners\n- Looking up partners by invitation token\n- Converting addresses to geolocation coordinates for partner location features\n"
+    },
+    {
+      "name": "Partner Users",
+      "x-displayName": "Partner Users",
+      "description": "Operations for managing users within partner organizations:\n- Listing users in a partner organization\n- Creating new users in partner organizations\n- Deleting users from partner organizations\n- Managing roles and role assignments for partner users\n\nThese operations allow Vendor organizations to control access and permissions for users in their partner network.\n"
+    }
+  ],
+  "x-tagGroups": [
+    {
+      "name": "APIs",
+      "tags": [
+        "Partners",
+        "Partner Users"
+      ]
+    },
+    {
+      "name": "Schemas",
+      "tags": [
+        "partner_schema"
+      ]
+    }
+  ],
+  "security": [
+    {
+      "EpilotAuth": []
+    },
+    {
+      "AsOrganization": []
+    }
+  ],
+  "paths": {
+    "/v1/partners/{id}/approve": {
+      "post": {
+        "operationId": "approvePartner",
+        "summary": "approvePartner",
+        "tags": [
+          "Partners"
+        ],
+        "description": "Approves a pending partner request, allowing the partner to begin collaboration.\n\nWhen a partner requests to join your organization's partner network, this endpoint\nis used to approve the request and activate the partnership.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "schema": {
+              "$ref": "#/components/schemas/PartnerId"
+            },
+            "required": true,
+            "description": "The unique identifier of the partner to approve"
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "Partner approved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Partner"
+                },
+                "example": {
+                  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
+                  "organization_id": "123",
+                  "company_name": "Acme Solar GmbH",
+                  "email": "partner@acme-solar.de",
+                  "status": "Invited",
+                  "created_at": "2024-01-15T10:30:00.000Z"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Unable to approve partner - partner may already be approved or in an invalid state"
+          },
+          "404": {
+            "description": "Partner not found"
+          }
+        }
+      }
+    },
+    "/v1/partners/{id}/reject": {
+      "post": {
+        "operationId": "rejectPartner",
+        "summary": "rejectPartner",
+        "tags": [
+          "Partners"
+        ],
+        "description": "Rejects a pending partner request, declining the partnership.\n\nWhen a partner requests to join your organization's partner network, this endpoint\nis used to reject the request if the partnership is not desired.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "schema": {
+              "$ref": "#/components/schemas/PartnerId"
+            },
+            "required": true,
+            "description": "The unique identifier of the partner to reject"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Partner rejected successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Partner"
+                },
+                "example": {
+                  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
+                  "organization_id": "123",
+                  "company_name": "Declined Partner Co",
+                  "email": "partner@declined.de",
+                  "status": "Rejected",
+                  "created_at": "2024-01-15T10:30:00.000Z"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Unable to reject partner - partner may already be rejected or in an invalid state"
+          },
+          "404": {
+            "description": "Partner not found"
+          }
+        }
+      }
+    },
+    "/v1/partners/assignables:search": {
+      "post": {
+        "operationId": "searchAssignable",
+        "summary": "searchAssignable",
+        "description": "Search for users and organizations that can be assigned to tasks, workflows, or entities.\n\nThis endpoint searches across your organization and all connected partner organizations\nto find assignable resources. Use this when you need to assign someone to a task,\nworkflow step, or entity and want to include partners in the search.\n\n**Results can include:**\n- `user`: Users in your organization\n- `partner_user`: Users in partner organizations\n- `partner_organization`: Partner organizations themselves (for organization-level assignments)\n- `ecp`: End Customer Portal users\n- `group`: User groups\n- `parent_organization_user`: Users from parent organization (for sub-organizations)\n\n**Pagination:** Use `from` and `size` parameters for paginated results.\n",
+        "tags": [
+          "Partners"
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "q": {
+                    "description": "Search query string to filter results by name or email",
+                    "type": "string",
+                    "default": "",
+                    "example": "john"
+                  },
+                  "from": {
+                    "description": "Starting offset for pagination (zero-based index)",
+                    "type": "integer",
+                    "minimum": 0,
+                    "default": 0,
+                    "example": 0
+                  },
+                  "size": {
+                    "description": "Maximum number of results to return per page",
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 1000,
+                    "default": 25,
+                    "example": 25
+                  },
+                  "org_ids": {
+                    "description": "Filter results to specific organization IDs. If not provided, searches all accessible organizations including partners.",
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/OrganizationId"
+                    },
+                    "example": [
+                      "123",
+                      "456"
+                    ]
+                  },
+                  "portalUsersEntityIdScope": {
+                    "description": "Entity ID to scope portal user search. Required when `types` includes `ecp`.\nWhen provided, only portal users related to the specified entity are returned\ninstead of placeholder users.\n",
+                    "type": "string",
+                    "default": "",
+                    "example": "f7c22299-ca72-4bca-8538-0a88eeefc947"
+                  },
+                  "types": {
+                    "description": "Filter results to specific types of assignables.\nIf not provided, defaults to all types except `parent_organization_user`.\n",
+                    "type": "array",
+                    "default": [
+                      "user",
+                      "partner_user",
+                      "partner_organization",
+                      "ecp",
+                      "group"
+                    ],
+                    "items": {
+                      "type": "string",
+                      "enum": [
+                        "user",
+                        "partner_user",
+                        "partner_organization",
+                        "ecp",
+                        "group",
+                        "parent_organization_user"
+                      ]
+                    }
+                  }
+                },
+                "required": [
+                  "q"
+                ]
+              },
+              "example": {
+                "q": "john",
+                "from": 0,
+                "size": 25,
+                "types": [
+                  "user",
+                  "partner_user"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "List of assignable results matching the search criteria",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "hits": {
+                      "description": "Total number of matching results (may exceed returned results for pagination)",
+                      "type": "integer",
+                      "example": 42
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Assignable"
+                      }
+                    }
+                  }
+                },
+                "example": {
+                  "hits": 2,
+                  "results": [
+                    {
+                      "type": "user",
+                      "display_name": "John Smith",
+                      "user_id": "456",
+                      "email": "john.smith@example.com",
+                      "org_id": "123",
+                      "status": "Active"
+                    },
+                    {
+                      "type": "partner_user",
+                      "display_name": "John Doe",
+                      "user_id": "789",
+                      "email": "john.doe@partner.com",
+                      "org_id": "321",
+                      "partner_id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
+                      "status": "Active"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request parameters"
+          }
+        }
+      }
+    },
+    "/v1/partners/assignables:batchGet": {
+      "post": {
+        "operationId": "batchGetAssignable",
+        "summary": "batchGetAssignable",
+        "description": "Retrieve multiple assignable users or groups by their IDs in a single request.\n\nUse this endpoint when you have a list of user or group IDs and need to fetch\ntheir full assignable information. This is more efficient than making multiple\nindividual requests.\n\nEach item in the request array should specify either a `user_id` or `group_id`.\n",
+        "tags": [
+          "Partners"
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "user_id": {
+                      "description": "User ID of the assignable to retrieve",
+                      "type": "string",
+                      "example": "456"
+                    },
+                    "org_id": {
+                      "description": "Organization ID of the assignable. If not provided, defaults to the caller's organization.",
+                      "type": "string",
+                      "example": "123"
+                    },
+                    "group_id": {
+                      "description": "Group ID of the assignable to retrieve (mutually exclusive with user_id)",
+                      "type": "string",
+                      "example": "group-789"
+                    }
+                  }
+                }
+              },
+              "example": [
+                {
+                  "user_id": "456",
+                  "org_id": "123"
+                },
+                {
+                  "user_id": "789",
+                  "org_id": "321"
+                },
+                {
+                  "group_id": "group-123"
+                }
+              ]
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "List of assignable results for the requested IDs",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "hits": {
+                      "description": "Total number of assignables found",
+                      "type": "integer",
+                      "example": 3
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Assignable"
+                      }
+                    }
+                  }
+                },
+                "example": {
+                  "hits": 2,
+                  "results": [
+                    {
+                      "type": "user",
+                      "display_name": "John Smith",
+                      "user_id": "456",
+                      "email": "john.smith@example.com",
+                      "org_id": "123",
+                      "status": "Active"
+                    },
+                    {
+                      "type": "user",
+                      "display_name": "Jane Doe",
+                      "user_id": "789",
+                      "email": "jane.doe@partner.com",
+                      "org_id": "321",
+                      "status": "Active"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - empty array or malformed request body"
+          }
+        }
+      }
+    },
+    "/v1/partner-directory/public/getPartnerByToken": {
+      "get": {
+        "operationId": "getPartnerByToken",
+        "summary": "getPartnerByToken",
+        "description": "Retrieves partner information using an invitation token.\n\nThis is a **public endpoint** that does not require authentication.\nIt is used during the partner onboarding flow to display partner information\nbefore the invited organization completes their registration.\n\nThe token is sent to the partner via email when they are invited.\n",
+        "security": [],
+        "tags": [
+          "Partners"
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "token",
+            "schema": {
+              "$ref": "#/components/schemas/InviteToken"
+            },
+            "required": true,
+            "description": "The invitation token received via email",
+            "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Partner information retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Partner"
+                },
+                "example": {
+                  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
+                  "organization_id": "123",
+                  "company_name": "Inviting Company GmbH",
+                  "email": "partner@invited.de",
+                  "status": "Invited",
+                  "created_at": "2024-01-15T10:30:00.000Z"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid or malformed token"
+          },
+          "404": {
+            "description": "Token not found or expired - the invitation may have already been used or is no longer valid"
+          }
+        }
+      }
+    },
+    "/v1/partner-directory/public/activate": {
+      "post": {
+        "operationId": "activatePartner",
+        "summary": "activatePartner",
+        "description": "Activates a partner account using an invitation token.\n\nThis is a **public endpoint** that does not require authentication.\nIt is called when an invited partner completes their registration to establish\nthe partnership between the two organizations.\n\n**Activation Flow:**\n1. Partner receives invitation email with token\n2. Partner clicks link and views invitation details (via `getPartnerByToken`)\n3. Partner completes registration form\n4. This endpoint is called to activate the partnership\n\nAfter activation, the partner organization can begin collaborating with\nthe inviting organization through shared entities and assignments.\n",
+        "security": [],
+        "tags": [
+          "Partners"
+        ],
+        "parameters": [
+          {
+            "name": "token",
+            "description": "The invitation token received via email",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/InviteToken"
+            },
+            "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ActivatePartnerPayload"
+              },
+              "example": {
+                "company_name": "New Partner GmbH",
+                "signed_up_email": "admin@newpartner.de",
+                "organization_id": "456"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Partner activated successfully - the partnership is now active"
+          },
+          "400": {
+            "description": "Invalid request - missing required fields or invalid data"
+          },
+          "404": {
+            "description": "Token not found or expired - the invitation may have already been used or is no longer valid"
+          },
+          "409": {
+            "description": "Partner already activated - this token has already been used"
+          }
+        }
+      }
+    },
+    "/v1/geolocation/text:search": {
+      "post": {
+        "operationId": "searchGeolocationForText",
+        "summary": "searchGeolocationForText",
+        "tags": [
+          "Partners"
+        ],
+        "description": "Converts an address string to geographic coordinates (latitude and longitude).\n\nThis endpoint is used to geocode partner addresses for location-based features such as:\n- Partner search by proximity\n- Displaying partners on a map\n- Calculating activity radius coverage\n\nThe address should be provided as a complete, well-formatted string for best results.\n",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SearchGeolocation"
+              },
+              "example": {
+                "address": "Auweg 1, 93055 Regensburg, DE"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Geolocation successfully retrieved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Geolocation"
+                },
+                "example": {
+                  "lat": 49.013,
+                  "lng": 12.101,
+                  "addressLabel": "Auweg 1, 93055 Regensburg, Germany",
+                  "relevance": 0.95
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - address field is missing or empty"
+          },
+          "404": {
+            "description": "Address could not be geocoded - no matching location found for the provided address"
+          }
+        }
+      }
+    },
+    "/v2/partners/{id}/invite": {
+      "post": {
+        "operationId": "invitePartnerV2",
+        "summary": "invitePartnerV2",
+        "tags": [
+          "Partners"
+        ],
+        "description": "Sends an invitation email to a partner organization to begin collaboration.\n\nThis endpoint generates an invitation token and sends an email to the partner\nwith a link to complete their registration. The partner can then accept the\ninvitation to establish a B2B partnership.\n\n**Invitation Flow:**\n1. Create a partner record (via entity API)\n2. Call this endpoint to send the invitation email\n3. Partner receives email with unique invitation link\n4. Partner activates their account via the public activation endpoint\n\nThe invitation email language can be customized via the request body.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "schema": {
+              "$ref": "#/components/schemas/PartnerId"
+            },
+            "required": true,
+            "description": "The unique identifier of the partner to invite"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PartnerInvitationPayload"
+              },
+              "example": {
+                "language": "de"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Invitation sent successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Partner"
+                },
+                "example": {
+                  "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc",
+                  "organization_id": "123",
+                  "company_name": "Invited Partner GmbH",
+                  "email": "contact@invited-partner.de",
+                  "status": "Invited",
+                  "invitation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+                  "created_at": "2024-01-15T10:30:00.000Z"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Unable to send invitation - partner may already be invited or email configuration is invalid"
+          },
+          "404": {
+            "description": "Partner not found"
+          }
+        }
+      }
+    },
+    "/v2/partners/{orgId}/users": {
+      "get": {
+        "operationId": "getPartnerUsers",
+        "summary": "getPartnerUsers",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Retrieves all users belonging to a partner organization along with their assigned roles.\n\nThis endpoint allows parent organizations to view and manage the users within\ntheir partner organizations. The response includes user details and their\nrole assignments within the partner organization.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner whose users to retrieve"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of partner users with their roles",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/PartnerUser"
+                      }
+                    }
+                  }
+                },
+                "example": {
+                  "results": [
+                    {
+                      "id": "456",
+                      "name": "John Smith",
+                      "email": "john.smith@partner.com",
+                      "status": "Active",
+                      "roles": [
+                        {
+                          "id": "role-123",
+                          "slug": "partner_admin",
+                          "name": "Partner Administrator"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - organization ID may be invalid or not a partner organization"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to view users in this partner organization"
+          },
+          "404": {
+            "description": "Partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      },
+      "post": {
+        "operationId": "createPartnerUser",
+        "summary": "createPartnerUser",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Creates a new user in a partner organization.\n\nThis endpoint allows parent organizations to create users directly within\ntheir partner organizations. The new user will receive an invitation email\nto set up their account.\n\nOptionally, roles can be assigned to the user at creation time.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The partner organization ID where the user will be created"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreatePartnerUserPayload"
+              },
+              "example": {
+                "email": "newuser@partner.com",
+                "language": "de",
+                "roles": [
+                  "role-123",
+                  "role-456"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "User created successfully - an invitation email has been sent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/User"
+                },
+                "example": {
+                  "id": "789",
+                  "email": "newuser@partner.com",
+                  "display_name": "newuser@partner.com",
+                  "status": "Pending"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - email may be invalid or user already exists in the organization"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to create users in this partner organization"
+          },
+          "404": {
+            "description": "Partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/partners/{orgId}/users/{userId}": {
+      "delete": {
+        "operationId": "deletePartnerUser",
+        "summary": "deletePartnerUser",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Removes a user from a partner organization.\n\nThis endpoint allows parent organizations to delete users from their partner\norganizations. The user will lose access to the partner organization immediately.\n\n**Note:** This action is permanent and cannot be undone.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner"
+          },
+          {
+            "in": "path",
+            "name": "userId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "The unique identifier of the user to delete",
+            "example": "456"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "User deleted successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                },
+                "example": {}
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - user ID may be invalid"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to delete users in this partner organization"
+          },
+          "404": {
+            "description": "User or partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/partners/{orgId}/roles": {
+      "get": {
+        "operationId": "getPartnerRoles",
+        "summary": "getPartnerRoles",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Retrieves all roles defined for a partner organization.\n\nRoles define the permissions that users in the partner organization have.\nParent organizations can use this endpoint to view available roles before\nassigning them to partner users.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner whose roles to retrieve"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of roles available in the partner organization",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/PartnerRole"
+                      }
+                    }
+                  }
+                },
+                "example": {
+                  "results": [
+                    {
+                      "id": "role-123",
+                      "slug": "partner_admin",
+                      "name": "Partner Administrator",
+                      "type": "share_role",
+                      "grants": [
+                        {
+                          "action": "entity-read",
+                          "resource": "entity:*:opportunity:*",
+                          "effect": "allow"
+                        }
+                      ]
+                    },
+                    {
+                      "id": "role-456",
+                      "slug": "partner_viewer",
+                      "name": "Partner Viewer",
+                      "type": "share_role",
+                      "grants": [
+                        {
+                          "action": "entity-read",
+                          "resource": "entity:*:*:*",
+                          "effect": "allow"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - organization ID may be invalid"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to view roles in this partner organization"
+          },
+          "404": {
+            "description": "Partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      },
+      "post": {
+        "operationId": "createPartnerRole",
+        "summary": "createPartnerRole",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Creates a new role for a partner organization.\n\nRoles define permissions for partner users. The parent organization can create\ncustom roles with specific permission grants to control what partner users\ncan access and modify.\n\n**Permission Grants:**\nEach role contains a list of grants that define allowed (or denied) actions\non specific resources. See the Grant schema for details on defining permissions.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner where the role will be created"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreatePartnerRolePayload"
+              },
+              "example": {
+                "name": "Partner Sales",
+                "slug": "partner_sales",
+                "grants": [
+                  {
+                    "action": "entity-read",
+                    "resource": "entity:*:opportunity:*",
+                    "effect": "allow"
+                  },
+                  {
+                    "action": "entity-update",
+                    "resource": "entity:*:opportunity:*",
+                    "effect": "allow"
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Role created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PartnerRole"
+                },
+                "example": {
+                  "id": "123:partner_sales",
+                  "slug": "partner_sales",
+                  "name": "Partner Sales",
+                  "type": "share_role",
+                  "grants": [
+                    {
+                      "action": "entity-read",
+                      "resource": "entity:*:opportunity:*",
+                      "effect": "allow"
+                    },
+                    {
+                      "action": "entity-update",
+                      "resource": "entity:*:opportunity:*",
+                      "effect": "allow"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - role name or slug may be invalid or already exists"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to create roles in this partner organization"
+          },
+          "404": {
+            "description": "Partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/partners/{orgId}/roles/{roleId}": {
+      "put": {
+        "operationId": "updatePartnerRole",
+        "summary": "updatePartnerRole",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Updates an existing role in a partner organization.\n\nUse this endpoint to modify the permissions (grants) or metadata of an existing\nrole. All users with this role will immediately have the updated permissions.\n\n**Note:** Changing role permissions affects all users currently assigned to the role.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner"
+          },
+          {
+            "in": "path",
+            "name": "roleId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "The unique identifier of the role to update",
+            "example": "123:partner_sales"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdatePartnerRolePayload"
+              },
+              "example": {
+                "name": "Partner Sales Updated",
+                "slug": "partner_sales",
+                "grants": [
+                  {
+                    "action": "entity-read",
+                    "resource": "entity:*:opportunity:*",
+                    "effect": "allow"
+                  },
+                  {
+                    "action": "entity-update",
+                    "resource": "entity:*:opportunity:*",
+                    "effect": "allow"
+                  },
+                  {
+                    "action": "entity-create",
+                    "resource": "entity:*:opportunity:*",
+                    "effect": "allow"
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Role updated successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PartnerRole"
+                },
+                "example": {
+                  "id": "123:partner_sales",
+                  "slug": "partner_sales",
+                  "name": "Partner Sales Updated",
+                  "type": "share_role",
+                  "grants": [
+                    {
+                      "action": "entity-read",
+                      "resource": "entity:*:opportunity:*",
+                      "effect": "allow"
+                    },
+                    {
+                      "action": "entity-update",
+                      "resource": "entity:*:opportunity:*",
+                      "effect": "allow"
+                    },
+                    {
+                      "action": "entity-create",
+                      "resource": "entity:*:opportunity:*",
+                      "effect": "allow"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - role data may be invalid"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to update roles in this partner organization"
+          },
+          "404": {
+            "description": "Role or partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deletePartnerRole",
+        "summary": "deletePartnerRole",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Delete a role from a partner organization",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner"
+          },
+          {
+            "in": "path",
+            "name": "roleId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "The role ID to delete"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Role deleted successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PartnerRole"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Unable to delete partner role"
+          },
+          "403": {
+            "description": "Forbidden - insufficient permissions or role cannot be deleted"
+          },
+          "404": {
+            "description": "Role not found"
+          },
+          "409": {
+            "description": "Role is currently assigned to users and cannot be deleted"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    },
+    "/v2/partners/{orgId}/users/{userId}/roles": {
+      "post": {
+        "operationId": "assignPartnerUserRoles",
+        "summary": "assignPartnerUserRoles",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Assigns one or more roles to a user in a partner organization.\n\nRoles define the permissions that the user has within the partner organization.\nMultiple roles can be assigned in a single request. The response indicates\nthe success or failure of each role assignment.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner"
+          },
+          {
+            "in": "path",
+            "name": "userId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "The unique identifier of the user to assign roles to",
+            "example": "456"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AssignRolesPayload"
+              },
+              "example": {
+                "roleIds": [
+                  "role-123",
+                  "role-456"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Role assignment results - each role assignment is processed individually",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "description": "Results for each role assignment attempt",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "roleId": {
+                            "type": "string",
+                            "description": "The role ID that was processed"
+                          },
+                          "success": {
+                            "type": "boolean",
+                            "description": "Whether the assignment was successful"
+                          },
+                          "data": {
+                            "type": "object",
+                            "description": "Additional data on success"
+                          },
+                          "error": {
+                            "type": "object",
+                            "description": "Error details on failure"
+                          }
+                        }
+                      }
+                    }
+                  }
+                },
+                "example": {
+                  "results": [
+                    {
+                      "roleId": "role-123",
+                      "success": true,
+                      "data": {}
+                    },
+                    {
+                      "roleId": "role-456",
+                      "success": true,
+                      "data": {}
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - role IDs may be invalid"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to assign roles in this partner organization"
+          },
+          "404": {
+            "description": "User or partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "unassignPartnerUserRoles",
+        "summary": "unassignPartnerUserRoles",
+        "tags": [
+          "Partner Users"
+        ],
+        "description": "Removes one or more roles from a user in a partner organization.\n\nThis endpoint removes the specified roles from the user, reducing their permissions\nwithin the partner organization. The response indicates the success or failure\nof each role removal.\n\n**Note:** Removing all roles from a user may result in the user having no access\nto the partner organization.\n",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "orgId",
+            "schema": {
+              "$ref": "#/components/schemas/OrganizationId"
+            },
+            "required": true,
+            "description": "The organization ID of the partner"
+          },
+          {
+            "in": "path",
+            "name": "userId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "The unique identifier of the user to remove roles from",
+            "example": "456"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AssignRolesPayload"
+              },
+              "example": {
+                "roleIds": [
+                  "role-456"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Role unassignment results - each role removal is processed individually",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "description": "Results for each role removal attempt",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "roleId": {
+                            "type": "string",
+                            "description": "The role ID that was processed"
+                          },
+                          "success": {
+                            "type": "boolean",
+                            "description": "Whether the removal was successful"
+                          },
+                          "data": {
+                            "type": "object",
+                            "description": "Additional data on success"
+                          },
+                          "error": {
+                            "type": "object",
+                            "description": "Error details on failure"
+                          }
+                        }
+                      }
+                    }
+                  }
+                },
+                "example": {
+                  "results": [
+                    {
+                      "roleId": "role-456",
+                      "success": true,
+                      "data": {}
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request - role IDs may be invalid"
+          },
+          "403": {
+            "description": "Access denied - caller does not have permission to unassign roles in this partner organization"
+          },
+          "404": {
+            "description": "User, role, or partner organization not found"
+          },
+          "500": {
+            "description": "Internal server error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      },
+      "AsOrganization": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "x-ivy-org-id",
+        "description": "Set organization id when using internal auth"
+      }
+    },
+    "schemas": {
+      "InviteToken": {
+        "type": "string",
+        "description": "A secure token used for partner invitation and activation. Sent via email to the invited partner.",
+        "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXJ0bmVySWQiOiIxMjM0NSJ9.abcdef"
+      },
+      "Partner": {
+        "type": "object",
+        "description": "Represents a partner organization in the partner directory.\n\nPartners go through a lifecycle from invitation to active collaboration:\n- **Pending**: Initial state when partner record is created\n- **Invited**: Invitation email has been sent to the partner\n- **Request**: Partner has requested to join (self-registration)\n- **Rejected**: Partnership request was declined\n- **Deleted**: Partner relationship has been terminated\n",
+        "properties": {
+          "id": {
+            "$ref": "#/components/schemas/PartnerId"
+          },
+          "organization_id": {
+            "description": "The organization ID of the parent organization that invited this partner",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/OrganizationId"
+              }
+            ]
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the partner record was created",
+            "example": "2022-02-08T04:44:32.246Z"
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional description of the partner or partnership",
+            "example": "Regional solar installation partner for Bavaria"
+          },
+          "company_name": {
+            "type": "string",
+            "description": "The legal or trading name of the partner organization",
+            "example": "Acme Solar GmbH"
+          },
+          "invitation_token": {
+            "description": "Secure token for partner activation (only present for invited partners)",
+            "type": "string",
+            "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+          },
+          "invitation_email": {
+            "deprecated": true,
+            "description": "Deprecated: Use 'email' instead. Email address used for the invitation.",
+            "type": "string",
+            "format": "email"
+          },
+          "email": {
+            "description": "Primary email address of the partner, used for invitation delivery",
+            "type": "string",
+            "format": "email",
+            "example": "contact@acme-solar.de"
+          },
+          "owner_email": {
+            "description": "Alternative email address where invitations should be sent (e.g., owner or admin email)",
+            "type": "string",
+            "format": "email",
+            "example": "owner@acme-solar.de"
+          },
+          "signed_up_email": {
+            "description": "Email address used by the partner when completing registration",
+            "type": "string",
+            "format": "email",
+            "example": "admin@acme-solar.de"
+          },
+          "partner_org_id": {
+            "description": "Organization ID of the partner organization (populated after activation)",
+            "type": "string",
+            "example": "456789"
+          },
+          "status": {
+            "type": "string",
+            "description": "Current status of the partner in the invitation/collaboration lifecycle",
+            "enum": [
+              "Pending",
+              "Request",
+              "Deleted",
+              "Invited",
+              "Rejected"
+            ]
+          }
+        }
+      },
+      "PartnerId": {
+        "type": "string",
+        "description": "Unique identifier for a partner record (UUID format)",
+        "example": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc"
+      },
+      "OrganizationId": {
+        "type": "string",
+        "description": "Unique identifier for an organization in the epilot platform",
+        "example": "123"
+      },
+      "ActivatePartnerPayload": {
+        "type": "object",
+        "description": "Payload for activating a partner account using an invitation token",
+        "properties": {
+          "company_name": {
+            "type": "string",
+            "description": "The official name of the partner's company",
+            "example": "Acme Solar GmbH"
+          },
+          "signed_up_email": {
+            "description": "Email address of the user completing the partner registration",
+            "type": "string",
+            "format": "email",
+            "example": "admin@acme-solar.de"
+          },
+          "organization_id": {
+            "description": "The organization ID of the partner's existing epilot organization (if they already have one)",
+            "type": "string",
+            "example": "456"
+          }
+        },
+        "required": [
+          "signed_up_email",
+          "organization_id"
+        ]
+      },
+      "PartnerInvitationPayload": {
+        "type": "object",
+        "description": "Configuration options for sending a partner invitation",
+        "properties": {
+          "language": {
+            "type": "string",
+            "description": "Language for the partner invitation email. Determines the email template language.",
+            "enum": [
+              "en",
+              "de"
+            ],
+            "default": "en",
+            "example": "de"
+          }
+        }
+      },
+      "Assignable": {
+        "description": "A user, organization, or group that can be assigned to tasks, workflows, or entities.\nThe `type` field discriminates between different assignable types.\n",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/AssignableUser"
+          },
+          {
+            "$ref": "#/components/schemas/AssignablePartnerUser"
+          },
+          {
+            "$ref": "#/components/schemas/AssignableOrganization"
+          },
+          {
+            "$ref": "#/components/schemas/AssignableEcpPlaceholder"
+          },
+          {
+            "$ref": "#/components/schemas/AssignableGroup"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "user": "#/components/schemas/AssignableUser",
+            "partner_user": "#/components/schemas/AssignablePartnerUser",
+            "partner_organization": "#/components/schemas/AssignableOrganization",
+            "ecp": "#/components/schemas/AssignableEcpPlaceholder",
+            "group": "#/components/schemas/AssignableGroup"
+          }
+        }
+      },
+      "BaseAssignable": {
+        "type": "object",
+        "description": "Common properties shared by all assignable types",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Discriminator field indicating the type of assignable",
+            "example": "user"
+          },
+          "display_name": {
+            "type": "string",
+            "description": "Human-readable name for display in UI (user name, organization name, or group name)",
+            "example": "John Smith"
+          },
+          "image_uri": {
+            "type": "object",
+            "description": "Profile image URLs for the assignable",
+            "properties": {
+              "original": {
+                "type": "string",
+                "format": "uri",
+                "description": "Full-resolution profile image URL",
+                "example": "https://epilot-staging-user-content.s3.eu-central-1.amazonaws.com/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png"
+              },
+              "thumbnail_32": {
+                "type": "string",
+                "format": "uri",
+                "description": "32x32 pixel thumbnail image URL for compact displays",
+                "example": "https://file.sls.epilot.io/v1/files/public/preview?w=32&h=32&key=/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png"
+              }
+            },
+            "required": [
+              "original"
+            ]
+          },
+          "org_id": {
+            "description": "Organization ID the assignable belongs to",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/OrganizationId"
+              }
+            ]
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the assignable was created",
+            "example": "2022-02-08T04:44:32.246Z"
+          },
+          "activated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the assignable was activated (for users, when they accepted their invitation)",
+            "example": "2022-02-08T04:44:32.246Z"
+          },
+          "status": {
+            "type": "string",
+            "description": "Current status of the assignable",
+            "enum": [
+              "Active",
+              "Pending",
+              "Deactivated",
+              "Deleted"
+            ]
+          }
+        },
+        "required": [
+          "type",
+          "display_name",
+          "org_id"
+        ]
+      },
+      "AssignableUser": {
+        "description": "A user within the caller's organization that can be assigned to tasks or entities",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseAssignable"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "user"
+                ],
+                "example": "user"
+              },
+              "display_name": {
+                "type": "string",
+                "description": "Full name of the user",
+                "example": "John Smith"
+              },
+              "user_id": {
+                "type": "string",
+                "description": "Unique identifier of the user",
+                "example": "456"
+              },
+              "email": {
+                "type": "string",
+                "format": "email",
+                "description": "Email address of the user",
+                "example": "john.smith@example.com"
+              }
+            }
+          }
+        ]
+      },
+      "AssignablePartnerUser": {
+        "description": "A user from a partner organization that can be assigned to shared tasks or entities",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseAssignable"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "partner_user"
+                ],
+                "example": "partner_user"
+              },
+              "display_name": {
+                "type": "string",
+                "description": "Full name of the partner user",
+                "example": "Jane Doe (Partner)"
+              },
+              "partner_id": {
+                "description": "ID of the partner relationship through which this user is accessible",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/PartnerId"
+                  }
+                ]
+              },
+              "user_id": {
+                "type": "string",
+                "description": "Unique identifier of the partner user",
+                "example": "789"
+              },
+              "email": {
+                "type": "string",
+                "format": "email",
+                "description": "Email address of the partner user",
+                "example": "jane.doe@partner.com"
+              }
+            }
+          }
+        ]
+      },
+      "AssignableGroup": {
+        "description": "A user group that can be assigned to tasks or entities. All members of the group will be notified/assigned.",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseAssignable"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "group"
+                ],
+                "example": "group"
+              },
+              "group_id": {
+                "type": "string",
+                "description": "Unique identifier of the user group",
+                "example": "group-456"
+              }
+            }
+          }
+        ]
+      },
+      "AssignableOrganization": {
+        "description": "A partner organization that can be assigned to tasks or entities at the organization level.\nUseful when you want to assign work to a partner company rather than a specific individual.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseAssignable"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "partner_organization"
+                ],
+                "example": "partner_organization"
+              },
+              "display_name": {
+                "type": "string",
+                "description": "Name of the partner organization",
+                "example": "Acme Solar GmbH"
+              },
+              "partner_id": {
+                "description": "ID of the partner relationship",
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/PartnerId"
+                  }
+                ]
+              },
+              "email": {
+                "type": "string",
+                "format": "email",
+                "description": "Primary contact email for the partner organization",
+                "example": "contact@acme-solar.de"
+              },
+              "geolocations": {
+                "type": "array",
+                "description": "Physical locations of the partner organization with addresses and coordinates",
+                "items": {
+                  "$ref": "#/components/schemas/AddressGeolocation"
+                }
+              },
+              "phone": {
+                "type": "string",
+                "description": "Primary contact phone number for the partner organization",
+                "example": "+49 941 123456"
+              },
+              "activity_radius": {
+                "type": "number",
+                "description": "Geographic service radius in kilometers - the area within which the partner operates",
+                "example": 50
+              }
+            },
+            "required": [
+              "type",
+              "display_name",
+              "partner_id"
+            ]
+          }
+        ]
+      },
+      "AssignableEcpPlaceholder": {
+        "description": "An End Customer Portal (ECP) user that can be assigned to tasks or entities.\nThese are external users who access the system through the customer portal.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseAssignable"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "ecp"
+                ],
+                "example": "ecp"
+              },
+              "display_name": {
+                "type": "string",
+                "description": "Name of the portal user",
+                "example": "Max Mustermann"
+              },
+              "user_id": {
+                "type": "string",
+                "description": "Unique identifier of the portal user",
+                "example": "ecp-456"
+              },
+              "email": {
+                "type": "string",
+                "format": "email",
+                "description": "Email address of the portal user",
+                "example": "max.mustermann@customer.de"
+              }
+            },
+            "required": [
+              "type",
+              "display_name",
+              "user_id"
+            ]
+          }
+        ]
+      },
+      "SearchGeolocation": {
+        "type": "object",
+        "description": "Request payload for geocoding an address to coordinates",
+        "properties": {
+          "address": {
+            "type": "string",
+            "description": "Full address string to convert to geographic coordinates.\nFor best results, include street, city, postal code, and country.\n",
+            "example": "Auweg 1, 93055 Regensburg, DE"
+          }
+        },
+        "required": [
+          "address"
+        ]
+      },
+      "Geolocation": {
+        "type": "object",
+        "description": "Geographic coordinates with optional metadata",
+        "properties": {
+          "lat": {
+            "type": "number",
+            "description": "Latitude coordinate (WGS84)",
+            "example": 49.013
+          },
+          "lng": {
+            "type": "number",
+            "description": "Longitude coordinate (WGS84)",
+            "example": 12.101
+          },
+          "addressLabel": {
+            "type": "string",
+            "description": "Normalized full address as returned by the geocoding service",
+            "example": "Auweg 1, 93055 Regensburg, Germany"
+          },
+          "relevance": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Confidence score for the geocoding result (0-1).\nValues closer to 1 indicate higher confidence that the coordinates match the input address.\n",
+            "example": 0.95
+          }
+        },
+        "required": [
+          "lat",
+          "lng"
+        ]
+      },
+      "Address": {
+        "type": "object",
+        "description": "Structured postal address",
+        "properties": {
+          "street": {
+            "type": "string",
+            "description": "Street name without house number",
+            "example": "Auweg"
+          },
+          "street_number": {
+            "type": "string",
+            "description": "House or building number",
+            "example": "10"
+          },
+          "city": {
+            "type": "string",
+            "description": "City or locality name",
+            "example": "Regensburg"
+          },
+          "postal_code": {
+            "type": "string",
+            "description": "Postal or ZIP code",
+            "example": "93055"
+          },
+          "country": {
+            "type": "string",
+            "description": "Country code (ISO 3166-1 alpha-2)",
+            "example": "DE"
+          }
+        }
+      },
+      "AddressGeolocation": {
+        "type": "object",
+        "description": "Combined address and geographic coordinates for a location",
+        "allOf": [
+          {
+            "type": "object",
+            "properties": {
+              "address": {
+                "$ref": "#/components/schemas/Address"
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/Geolocation"
+          }
+        ],
+        "required": [
+          "address"
+        ]
+      },
+      "PartnerUser": {
+        "type": "object",
+        "description": "A user within a partner organization, including their assigned roles",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for the user",
+            "example": "456"
+          },
+          "name": {
+            "type": "string",
+            "description": "Full name of the user",
+            "example": "John Doe"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Email address of the user",
+            "example": "user@partner.com"
+          },
+          "status": {
+            "type": "string",
+            "description": "Current status of the user account:\n- Active: User has completed registration and can access the system\n- Pending: User has been invited but not yet completed registration\n- Deactivated: User account has been disabled\n",
+            "example": "Active"
+          },
+          "image": {
+            "type": "object",
+            "description": "Profile image URLs for the user",
+            "properties": {
+              "original": {
+                "type": "string",
+                "format": "uri",
+                "description": "Full-resolution profile image URL"
+              },
+              "thumbnail_32": {
+                "type": "string",
+                "format": "uri",
+                "description": "32x32 pixel thumbnail image URL"
+              }
+            }
+          },
+          "roles": {
+            "type": "array",
+            "description": "List of roles assigned to the user within the partner organization",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "Unique identifier for the role",
+                  "example": "123:partner_admin"
+                },
+                "slug": {
+                  "type": "string",
+                  "description": "URL-friendly role identifier",
+                  "example": "partner_admin"
+                },
+                "name": {
+                  "type": "string",
+                  "description": "Human-readable role name",
+                  "example": "Partner Administrator"
+                }
+              },
+              "required": [
+                "id",
+                "slug",
+                "name"
+              ]
+            }
+          }
+        },
+        "required": [
+          "id",
+          "email",
+          "status",
+          "roles"
+        ]
+      },
+      "CreatePartnerUserPayload": {
+        "type": "object",
+        "description": "Request payload for creating a new user in a partner organization",
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Email address for the new user. An invitation will be sent to this address.",
+            "example": "newuser@partner.com"
+          },
+          "language": {
+            "type": "string",
+            "enum": [
+              "en",
+              "de"
+            ],
+            "description": "Preferred language for the user. Determines the language of the invitation email and default UI language.",
+            "example": "de"
+          },
+          "roles": {
+            "type": "array",
+            "description": "Role IDs to automatically assign to the user upon creation.\nIf not provided, the user will have no roles until manually assigned.\n",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "123:partner_viewer"
+            ]
+          }
+        },
+        "required": [
+          "email"
+        ]
+      },
+      "CreatePartnerRolePayload": {
+        "type": "object",
+        "description": "Request payload for creating a new role in a partner organization",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Human-readable display name for the role",
+            "example": "Partner Administrator"
+          },
+          "slug": {
+            "type": "string",
+            "description": "URL-friendly identifier for the role (lowercase, underscores allowed)",
+            "example": "partner_admin",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "grants": {
+            "type": "array",
+            "description": "Permission grants that define what users with this role can do.\nEach grant specifies an action and resource pattern.\n",
+            "items": {
+              "$ref": "#/components/schemas/GrantWithDependencies"
+            }
+          }
+        },
+        "required": [
+          "name",
+          "slug",
+          "grants"
+        ]
+      },
+      "UpdatePartnerRolePayload": {
+        "description": "Request payload for updating an existing role in a partner organization",
+        "allOf": [
+          {
+            "properties": {
+              "grants": {
+                "type": "array",
+                "description": "Updated list of permission grants for the role",
+                "items": {
+                  "$ref": "#/components/schemas/GrantWithDependencies"
+                }
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/BaseRoleForCreate"
+          }
+        ]
+      },
+      "Grant": {
+        "type": "object",
+        "description": "A permission grant that allows or denies a specific action on a resource.\n\nGrants are the building blocks of roles and define what users can do within the system.\n",
+        "properties": {
+          "action": {
+            "type": "string",
+            "description": "The action being granted or denied.\nCommon actions include: entity-read, entity-create, entity-update, entity-delete\n",
+            "example": "entity-read"
+          },
+          "resource": {
+            "type": "string",
+            "description": "The resource pattern this grant applies to.\nFormat: entity:<org_id>:<schema>:<entity_id>\nUse wildcards (*) to match multiple resources.\n",
+            "example": "entity:123:contact:*"
+          },
+          "effect": {
+            "type": "string",
+            "default": "allow",
+            "description": "Whether this grant allows or denies the action",
+            "enum": [
+              "allow",
+              "deny"
+            ]
+          },
+          "conditions": {
+            "type": "array",
+            "description": "Additional conditions that must be met for this grant to apply",
+            "items": {
+              "$ref": "#/components/schemas/GrantCondition"
+            }
+          }
+        },
+        "required": [
+          "action"
+        ]
+      },
+      "GrantWithDependencies": {
+        "description": "A grant with optional dependent grants that are automatically included when this grant is assigned",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Grant"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "dependencies": {
+                "description": "Additional grants that are automatically included when this grant is assigned.\nDependencies are expanded and stored with the role to ensure users have all\nnecessary permissions for the primary action.\n",
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Grant"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "GrantCondition": {
+        "description": "An additional condition that must be met for a grant to apply.\nConditions allow fine-grained control over when permissions are active.\n",
+        "allOf": [
+          {
+            "type": "object",
+            "required": [
+              "operation"
+            ]
+          },
+          {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EqualsCondition"
+              }
+            ]
+          }
+        ]
+      },
+      "EqualsCondition": {
+        "type": "object",
+        "description": "A condition that checks if an attribute equals one of the specified values.\nThe grant only applies when the condition is satisfied.\n",
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "description": "The attribute path to check (dot notation for nested attributes).\nExample: workflows.primary.task_name checks the task name in the primary workflow.\n",
+            "example": "workflows.primary.task_name"
+          },
+          "operation": {
+            "type": "string",
+            "description": "The comparison operation to perform",
+            "enum": [
+              "equals"
+            ]
+          },
+          "values": {
+            "type": "array",
+            "description": "List of values to match against - the condition is true if the attribute equals any of these values",
+            "items": {
+              "type": "string",
+              "example": "Qualification"
+            }
+          }
+        },
+        "required": [
+          "attribute",
+          "operation",
+          "values"
+        ]
+      },
+      "RoleId": {
+        "type": "string",
+        "description": "Unique identifier for a role, combining organization ID and role slug.\nFormat: <organization_id>:<slug>\n",
+        "example": "123:owner"
+      },
+      "BaseRoleForCreate": {
+        "type": "object",
+        "description": "Base schema for creating or updating a role",
+        "properties": {
+          "id": {
+            "$ref": "#/components/schemas/RoleId"
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable display name for the role",
+            "example": "Owner"
+          },
+          "slug": {
+            "type": "string",
+            "description": "URL-friendly identifier for the role (lowercase, no spaces)",
+            "example": "owner",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "grants": {
+            "type": "array",
+            "description": "List of permission grants that define what users with this role can do",
+            "items": {
+              "$ref": "#/components/schemas/Grant"
+            }
+          }
+        },
+        "required": [
+          "name",
+          "slug",
+          "grants"
+        ]
+      },
+      "PartnerRole": {
+        "type": "object",
+        "description": "A role definition for users in a partner organization",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for the role (format: org_id:slug)",
+            "example": "123:partner_admin"
+          },
+          "slug": {
+            "type": "string",
+            "description": "URL-friendly identifier for the role",
+            "example": "partner_admin"
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable display name for the role",
+            "example": "Partner Administrator"
+          },
+          "type": {
+            "type": "string",
+            "description": "Type of role. Partner roles are typically 'share_role' indicating\nthey are designed for cross-organization sharing scenarios.\n",
+            "example": "share_role"
+          },
+          "grants": {
+            "type": "array",
+            "description": "List of permission grants that define what users with this role can do",
+            "items": {
+              "$ref": "#/components/schemas/Grant"
+            }
+          }
+        },
+        "required": [
+          "id",
+          "slug",
+          "name",
+          "grants"
+        ]
+      },
+      "AssignRolesPayload": {
+        "type": "object",
+        "description": "Request payload for assigning or unassigning roles to/from a user",
+        "properties": {
+          "roleIds": {
+            "type": "array",
+            "description": "Array of role IDs to assign or unassign",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "123:partner_admin",
+              "123:partner_viewer"
+            ]
+          }
+        },
+        "required": [
+          "roleIds"
+        ]
+      },
+      "User": {
+        "type": "object",
+        "description": "A user account in the epilot platform",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique identifier for the user",
+            "example": "456"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Email address of the user",
+            "example": "user@example.com"
+          },
+          "display_name": {
+            "type": "string",
+            "description": "Full name of the user for display purposes",
+            "example": "John Doe"
+          },
+          "status": {
+            "type": "string",
+            "description": "Current status of the user account:\n- Active: User has completed registration and can access the system\n- Pending: User has been invited but not yet completed registration\n- Deactivated: User account has been disabled\n",
+            "example": "Active",
+            "enum": [
+              "Active",
+              "Pending",
+              "Deactivated"
+            ]
+          }
+        }
+      }
+    }
+  },
+  "servers": [
+    {
+      "url": "https://partner-directory-api.sls.epilot.io"
+    }
+  ]
+}