@epilot/sdk 2.0.0-beta.2 → 2.0.0-beta.4

package/definitions/permissions.json

@@ -0,0 +1,1480 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Permissions API",
+    "version": "1.2.0",
+    "description": "Flexible Role-based Access Control for epilot"
+  },
+  "tags": [
+    {
+      "name": "Roles",
+      "description": "Manage roles and grants"
+    },
+    {
+      "name": "Assignments",
+      "description": "Assign roles to users"
+    }
+  ],
+  "security": [
+    {
+      "EpilotAuth": []
+    },
+    {
+      "EpilotOrg": []
+    }
+  ],
+  "paths": {
+    "/v1/permissions/me": {
+      "get": {
+        "operationId": "listCurrentRoles",
+        "summary": "listCurrentRoles",
+        "description": "Returns roles and grants assigned to current user",
+        "tags": [
+          "Roles"
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "roles": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Role"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/permissions/roles": {
+      "get": {
+        "operationId": "listAllRoles",
+        "summary": "listAllRoles",
+        "description": "Returns list of all roles in organization",
+        "tags": [
+          "Roles"
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "roles": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Role"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "createRole",
+        "summary": "createRole",
+        "description": "Create role",
+        "tags": [
+          "Roles"
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateRolePayload"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Role"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid role configuration",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "examples": {
+                  "parent_role_invalid_type": {
+                    "summary": "Parent role must be org_role or share_role",
+                    "value": {
+                      "message": "Parent role must be org_role or share_role, got user_role"
+                    }
+                  },
+                  "parent_role_different_org": {
+                    "summary": "Parent org_role must be in the same organization",
+                    "value": {
+                      "message": "Parent org_role must be in the same organization"
+                    }
+                  },
+                  "parent_role_max_hierarchy": {
+                    "summary": "Parent role cannot itself have a parent",
+                    "value": {
+                      "message": "Parent role cannot itself have a parent (max 2 levels of hierarchy)"
+                    }
+                  },
+                  "circular_dependency_self": {
+                    "summary": "Role cannot be its own parent",
+                    "value": {
+                      "message": "Role cannot be its own parent"
+                    }
+                  },
+                  "circular_dependency_detected": {
+                    "summary": "Circular dependency detected",
+                    "value": {
+                      "message": "Circular dependency detected: role 123:child would create a cycle"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Parent role does not exist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "examples": {
+                  "parent_role_not_found": {
+                    "summary": "Parent role does not exist",
+                    "value": {
+                      "message": "Parent role 123:nonexistent does not exist"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/permissions/roles:search": {
+      "post": {
+        "operationId": "searchRoles",
+        "summary": "searchRoles",
+        "description": "Search Roles",
+        "tags": [
+          "Roles"
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RoleSearchInput"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "hits": {
+                      "type": "number"
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Role"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/permissions/roles/{roleId}": {
+      "get": {
+        "operationId": "getRole",
+        "summary": "getRole",
+        "description": "Get role by id",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "roleId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Role"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "operationId": "putRole",
+        "summary": "putRole",
+        "description": "Create or update role",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "roleId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RolePayload"
+              },
+              "x-examples": {
+                "User role: manager": {
+                  "description": "Example manager role",
+                  "value": {
+                    "id": "123:manager",
+                    "name": "Manager",
+                    "slug": "manager",
+                    "type": "user_role",
+                    "organization_id": "123",
+                    "grants": [
+                      {
+                        "action": "entity:view",
+                        "resource": "*"
+                      },
+                      {
+                        "action": "entity:update",
+                        "resource": "*"
+                      },
+                      {
+                        "action": "user:view"
+                      },
+                      {
+                        "action": "user:invite"
+                      },
+                      {
+                        "action": "role:view"
+                      },
+                      {
+                        "action": "role:create"
+                      },
+                      {
+                        "action": "role:assign"
+                      },
+                      {
+                        "action": "entity:view",
+                        "resource": "file:*",
+                        "conditions": [
+                          {
+                            "attribute": "_tags",
+                            "operation": "equals",
+                            "values": [
+                              "offer",
+                              "contract"
+                            ]
+                          }
+                        ]
+                      },
+                      {
+                        "action": "message:view",
+                        "dependencies": [
+                          {
+                            "action": "entity:view",
+                            "resource": "message*"
+                          },
+                          {
+                            "action": "entity:view",
+                            "resource": "thread*"
+                          }
+                        ]
+                      },
+                      {
+                        "action": "message:send",
+                        "dependencies": [
+                          {
+                            "action": "entity:*",
+                            "resource": "message*"
+                          },
+                          {
+                            "action": "entity:*",
+                            "resource": "thread*"
+                          }
+                        ]
+                      },
+                      {
+                        "action": "workflow:*"
+                      }
+                    ]
+                  }
+                },
+                "User role: employee": {
+                  "description": "Example employee role",
+                  "value": {
+                    "id": "123:employee",
+                    "name": "Employee",
+                    "slug": "employee",
+                    "type": "user_role",
+                    "organization_id": "123",
+                    "grants": [
+                      {
+                        "action": "entity:view",
+                        "resource": "*"
+                      },
+                      {
+                        "action": "entity:update",
+                        "resource": "*"
+                      },
+                      {
+                        "action": "user:view"
+                      },
+                      {
+                        "action": "message:view",
+                        "dependencies": [
+                          {
+                            "action": "entity:view",
+                            "resource": "message*"
+                          },
+                          {
+                            "action": "entity:view",
+                            "resource": "thread*"
+                          }
+                        ]
+                      },
+                      {
+                        "action": "message:send",
+                        "dependencies": [
+                          {
+                            "action": "entity:*",
+                            "resource": "message*"
+                          },
+                          {
+                            "action": "entity:*",
+                            "resource": "thread*"
+                          }
+                        ]
+                      },
+                      {
+                        "action": "workflow:execution:*"
+                      }
+                    ]
+                  }
+                },
+                "User role: administrator": {
+                  "description": "Example administrator role",
+                  "value": {
+                    "id": "123:administrator",
+                    "name": "Administrator",
+                    "slug": "administrator",
+                    "type": "user_role",
+                    "organization_id": "123",
+                    "grants": [
+                      {
+                        "action": "*",
+                        "resource": "*"
+                      }
+                    ]
+                  }
+                },
+                "Organization root role": {
+                  "description": "Example organization root role. Must be satisifed for all org queries.",
+                  "value": {
+                    "id": "123:root",
+                    "name": "Organization root role",
+                    "slug": "root",
+                    "type": "org_role",
+                    "organization_id": "123",
+                    "grants": [
+                      {
+                        "action": "*",
+                        "resource": "*"
+                      },
+                      {
+                        "action": "webhook:*",
+                        "effect": "deny"
+                      }
+                    ]
+                  }
+                },
+                "Share role": {
+                  "description": "Example share role. This can be assigned to users in other organizations",
+                  "value": {
+                    "id": "123:example_share_role",
+                    "name": "Example opportunity share role",
+                    "slug": "example_share_role",
+                    "type": "share_role",
+                    "organization_id": "123",
+                    "grants": [
+                      {
+                        "action": "entity:view",
+                        "resource": "opportunity:123456"
+                      },
+                      {
+                        "action": "entity:edit",
+                        "resource": "opportunity:123456"
+                      },
+                      {
+                        "action": "workflow:execution:*"
+                      },
+                      {
+                        "action": "message:*"
+                      },
+                      {
+                        "action": "entity:*",
+                        "resource": "message*"
+                      },
+                      {
+                        "action": "entity:*",
+                        "resource": "thread*"
+                      }
+                    ]
+                  }
+                },
+                "Partner role": {
+                  "description": "Example partner role. This can be given to a partner organization, who can then assign it to their users",
+                  "value": {
+                    "id": "123:example_partner_role",
+                    "name": "Example opportunity share role",
+                    "slug": "example_partner_role",
+                    "type": "partner_role",
+                    "organization_id": "123",
+                    "partner_org_id": "456",
+                    "grants": [
+                      {
+                        "action": "entity:view",
+                        "resource": "opportunity*"
+                      },
+                      {
+                        "action": "entity:edit",
+                        "resource": "opportunity*"
+                      },
+                      {
+                        "action": "workflow:execution:*"
+                      },
+                      {
+                        "action": "message:*"
+                      },
+                      {
+                        "action": "entity:*",
+                        "resource": "message*"
+                      },
+                      {
+                        "action": "entity:*",
+                        "resource": "thread*"
+                      }
+                    ]
+                  }
+                },
+                "Portal role": {
+                  "description": "Example portal role. Implicitly used by end users of portals",
+                  "value": {
+                    "id": "123:default_end_customer_portal_role",
+                    "name": "Default End Customer Portal Role",
+                    "slug": "default_end_customer_portal_role",
+                    "type": "portal_role",
+                    "organization_id": "123",
+                    "grants": [
+                      {
+                        "action": "entity:attribute:view",
+                        "resource": "contact:*/*"
+                      },
+                      {
+                        "action": "entity:edit",
+                        "resource": "opportunity*"
+                      }
+                    ]
+                  }
+                },
+                "User role with parent": {
+                  "description": "Example user role that inherits from a parent role",
+                  "value": {
+                    "id": "123:limited_manager",
+                    "name": "Limited Manager",
+                    "slug": "limited_manager",
+                    "type": "user_role",
+                    "organization_id": "123",
+                    "parent_role": "123:manager",
+                    "grants": [
+                      {
+                        "action": "entity:view",
+                        "resource": "contact:*"
+                      },
+                      {
+                        "action": "entity:edit",
+                        "resource": "contact:*"
+                      }
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Role"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request - Invalid role configuration",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "examples": {
+                  "parent_role_invalid_type": {
+                    "summary": "Parent role must be org_role or share_role",
+                    "value": {
+                      "message": "Parent role must be org_role or share_role, got user_role"
+                    }
+                  },
+                  "parent_role_different_org": {
+                    "summary": "Parent org_role must be in the same organization",
+                    "value": {
+                      "message": "Parent org_role must be in the same organization"
+                    }
+                  },
+                  "parent_role_max_hierarchy": {
+                    "summary": "Parent role cannot itself have a parent",
+                    "value": {
+                      "message": "Parent role cannot itself have a parent (max 2 levels of hierarchy)"
+                    }
+                  },
+                  "circular_dependency_self": {
+                    "summary": "Role cannot be its own parent",
+                    "value": {
+                      "message": "Role cannot be its own parent"
+                    }
+                  },
+                  "circular_dependency_detected": {
+                    "summary": "Circular dependency detected",
+                    "value": {
+                      "message": "Circular dependency detected: role 123:child would create a cycle"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found - Parent role does not exist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                },
+                "examples": {
+                  "parent_role_not_found": {
+                    "summary": "Parent role does not exist",
+                    "value": {
+                      "message": "Parent role 123:nonexistent does not exist"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteRole",
+        "summary": "deleteRole",
+        "description": "Delete role by id",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "roleId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Role"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/permissions/refresh": {
+      "get": {
+        "operationId": "refreshPermissions",
+        "summary": "refreshPermissions",
+        "description": "Makes sure the user has a role in the organization",
+        "tags": [
+          "Roles"
+        ],
+        "responses": {
+          "200": {
+            "description": "Refreshed succesfully"
+          }
+        }
+      }
+    },
+    "/v1/permissions/assignments/{userId}": {
+      "get": {
+        "operationId": "getAssignedRolesForUser",
+        "summary": "getAssignedRolesForUser",
+        "description": "Get list of assigned roles by user id",
+        "tags": [
+          "Assignments"
+        ],
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/UserId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Assignments"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "operationId": "assignRoles",
+        "summary": "assignRoles",
+        "description": "Assign / unassign roles to users.",
+        "tags": [
+          "Assignments"
+        ],
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/UserId"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/Assignments"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Assignments"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/permissions/assignments/{userId}/{roleId}": {
+      "post": {
+        "operationId": "addAssignment",
+        "summary": "addAssignment",
+        "description": "Assign a user to a role.\n\nUse the `x-epilot-org-id` header to assign share roles to users in other orgs\n",
+        "tags": [
+          "Assignments"
+        ],
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/UserId"
+            }
+          },
+          {
+            "name": "roleId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Assignment"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "removeAssignment",
+        "summary": "removeAssignment",
+        "description": "Remove role assignment from user",
+        "tags": [
+          "Assignments"
+        ],
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/UserId"
+            }
+          },
+          {
+            "name": "roleId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Assignment"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/permissions/assignments": {
+      "get": {
+        "operationId": "listAllAssignments",
+        "summary": "listAllAssignments",
+        "description": "Returns list of all assignments in organization",
+        "tags": [
+          "Assignments"
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "assignments": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Assignment"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      },
+      "EpilotOrg": {
+        "description": "Overrides the target organization to allow shared tenantaccess",
+        "name": "x-epilot-org-id",
+        "in": "header",
+        "type": "apiKey"
+      }
+    },
+    "schemas": {
+      "Grant": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "example": "entity-read"
+          },
+          "resource": {
+            "type": "string",
+            "example": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947"
+          },
+          "effect": {
+            "type": "string",
+            "default": "allow",
+            "enum": [
+              "allow",
+              "deny"
+            ]
+          },
+          "conditions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/GrantCondition"
+            }
+          }
+        },
+        "required": [
+          "action"
+        ]
+      },
+      "GrantWithDependencies": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Grant"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "dependencies": {
+                "description": "Provided additional dependencies, exploded when storing the role",
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Grant"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "GrantCondition": {
+        "allOf": [
+          {
+            "description": "An additional condition that must be met for the grant",
+            "type": "object",
+            "required": [
+              "operation"
+            ]
+          },
+          {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EqualsCondition"
+              }
+            ]
+          }
+        ]
+      },
+      "EqualsCondition": {
+        "description": "Check if attribute equals to any of the values",
+        "type": "object",
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "example": "workflows.primary.task_name"
+          },
+          "operation": {
+            "type": "string",
+            "enum": [
+              "equals"
+            ]
+          },
+          "values": {
+            "type": "array",
+            "items": {
+              "example": "Qualification"
+            }
+          }
+        },
+        "required": [
+          "attribute",
+          "operation",
+          "values"
+        ]
+      },
+      "RoleId": {
+        "type": "string",
+        "example": "123:owner",
+        "description": "Format: <organization_id>:<slug>"
+      },
+      "BaseRole": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "$ref": "#/components/schemas/RoleId"
+          },
+          "name": {
+            "type": "string",
+            "example": "Owner",
+            "description": "Human-friendly name for the role"
+          },
+          "slug": {
+            "type": "string",
+            "example": "owner",
+            "description": "URL-friendly name for the role"
+          },
+          "type": {
+            "type": "string",
+            "description": "Type of the role"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "example": "2028-07-21T17:32:28Z",
+            "description": "date and time then the role will expire"
+          },
+          "organization_id": {
+            "$ref": "#/components/schemas/OrganizationId"
+          },
+          "grants": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Grant"
+            },
+            "description": "List of grants (permissions) applied to the role"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "slug",
+          "type",
+          "organization_id",
+          "grants"
+        ]
+      },
+      "BaseRoleForCreate": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "$ref": "#/components/schemas/RoleId"
+          },
+          "name": {
+            "type": "string",
+            "example": "Owner",
+            "description": "Human-friendly name for the role"
+          },
+          "slug": {
+            "type": "string",
+            "example": "owner",
+            "description": "URL-friendly name for the role"
+          },
+          "type": {
+            "type": "string",
+            "description": "Type of the role"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "example": "2028-07-21T17:32:28Z",
+            "description": "date and time then the role will expire"
+          },
+          "organization_id": {
+            "$ref": "#/components/schemas/OrganizationId"
+          },
+          "grants": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Grant"
+            },
+            "description": "List of grants (permissions) applied to the role"
+          }
+        },
+        "required": [
+          "name",
+          "slug",
+          "type",
+          "grants"
+        ]
+      },
+      "UserRole": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRole"
+          },
+          {
+            "description": "A standard user role. Must be explicitly assigned to users.",
+            "properties": {
+              "type": {
+                "enum": [
+                  "user_role"
+                ]
+              },
+              "parent_role": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/RoleId"
+                  },
+                  {
+                    "description": "Optional parent role that this role inherits from. Must be an `org_role` or `share_role`."
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      },
+      "OrgRole": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRole"
+          },
+          {
+            "description": "A role automatically applied to all users in an organization.",
+            "properties": {
+              "type": {
+                "enum": [
+                  "org_role"
+                ]
+              },
+              "pricing_tier": {
+                "type": "string",
+                "description": "The pricing tier of the organization this root role is based on",
+                "example": "Professional"
+              }
+            }
+          }
+        ]
+      },
+      "ShareRole": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRole"
+          },
+          {
+            "description": "A role that can be assigned to users in other organizations for sharing purposes.",
+            "properties": {
+              "type": {
+                "enum": [
+                  "share_role"
+                ]
+              }
+            }
+          }
+        ]
+      },
+      "PartnerRole": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRole"
+          },
+          {
+            "description": "A role that appears in another organization's role list that can be assigned but not modified by the partner organization.",
+            "properties": {
+              "type": {
+                "enum": [
+                  "partner_role"
+                ]
+              },
+              "partner_org_id": {
+                "allOf": [
+                  {
+                    "description": "Partner organization who can assign this role to their users."
+                  },
+                  {
+                    "$ref": "#/components/schemas/OrganizationId"
+                  }
+                ]
+              },
+              "vendor_enforced_user_limit": {
+                "type": "integer",
+                "readOnly": true,
+                "description": "Maximum number of users that can be assigned this role (vendor-enforced limit, can only be set via internal auth)"
+              }
+            }
+          }
+        ]
+      },
+      "PortalRole": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRole"
+          },
+          {
+            "description": "A role that is applied to end customers and installers using the Portals",
+            "properties": {
+              "type": {
+                "enum": [
+                  "portal_role"
+                ]
+              }
+            }
+          }
+        ]
+      },
+      "Role": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/UserRole"
+          },
+          {
+            "$ref": "#/components/schemas/OrgRole"
+          },
+          {
+            "$ref": "#/components/schemas/ShareRole"
+          },
+          {
+            "$ref": "#/components/schemas/PartnerRole"
+          },
+          {
+            "$ref": "#/components/schemas/PortalRole"
+          }
+        ]
+      },
+      "RolePayload": {
+        "allOf": [
+          {
+            "properties": {
+              "grants": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/GrantWithDependencies"
+                }
+              }
+            }
+          },
+          {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/UserRole"
+              },
+              {
+                "$ref": "#/components/schemas/OrgRole"
+              },
+              {
+                "$ref": "#/components/schemas/ShareRole"
+              },
+              {
+                "$ref": "#/components/schemas/PartnerRole"
+              },
+              {
+                "$ref": "#/components/schemas/PortalRole"
+              }
+            ]
+          }
+        ]
+      },
+      "Assignment": {
+        "type": "object",
+        "description": "A role attached to an user",
+        "properties": {
+          "user_id": {
+            "$ref": "#/components/schemas/UserId"
+          },
+          "roles": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          }
+        }
+      },
+      "InternalAssignment": {
+        "type": "object",
+        "description": "A role attached to an user",
+        "properties": {
+          "userId": {
+            "$ref": "#/components/schemas/UserId"
+          },
+          "roles": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          }
+        }
+      },
+      "OrgAssignments": {
+        "type": "object",
+        "description": "All roles attached to an users of an organization",
+        "properties": {
+          "organizationId": {
+            "$ref": "#/components/schemas/OrganizationId"
+          },
+          "assignments": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/InternalAssignment"
+            }
+          }
+        }
+      },
+      "OrgRoles": {
+        "type": "object",
+        "description": "All roles attached to an users of an organization",
+        "properties": {
+          "organizationId": {
+            "$ref": "#/components/schemas/OrganizationId"
+          },
+          "roles": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Role"
+            }
+          }
+        }
+      },
+      "Assignments": {
+        "type": "array",
+        "description": "List of role ids attached to an user",
+        "items": {
+          "$ref": "#/components/schemas/RoleId"
+        }
+      },
+      "UserId": {
+        "type": "string",
+        "example": "1",
+        "description": "Id of a user"
+      },
+      "OrganizationId": {
+        "type": "string",
+        "example": "123",
+        "description": "Id of an organization"
+      },
+      "Slug": {
+        "type": "string",
+        "example": "owner",
+        "description": "Slug of a role; for a role with id = 123:manager -> 123 is org_id & manager is slug"
+      },
+      "RoleSearchInput": {
+        "type": "object",
+        "properties": {
+          "role_ids": {
+            "type": "array",
+            "description": "List of role ids to filter by",
+            "example": [
+              "123:manager",
+              "456:owner"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/RoleId"
+            }
+          },
+          "org_ids": {
+            "type": "array",
+            "description": "List of organization ids to filter by",
+            "example": [
+              "123",
+              "456"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/OrganizationId"
+            }
+          },
+          "slugs": {
+            "type": "array",
+            "description": "List of role slugs to filter by",
+            "example": [
+              "manager",
+              "owner"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/Slug"
+            }
+          },
+          "query": {
+            "type": "string",
+            "description": "Input to search across fields",
+            "example": "Administrator"
+          },
+          "limit": {
+            "type": "number",
+            "description": "The Number of roles to return",
+            "example": 1,
+            "minimum": 1,
+            "default": 50
+          },
+          "offset": {
+            "type": "number",
+            "description": "The number of roles to skip before starting to collect the result set",
+            "example": 1,
+            "minimum": 1,
+            "default": 0
+          }
+        }
+      },
+      "CreateRolePayload": {
+        "allOf": [
+          {
+            "properties": {
+              "grants": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/GrantWithDependencies"
+                }
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/BaseRoleForCreate"
+          },
+          {
+            "oneOf": [
+              {
+                "description": "A standard user role. Must be explicitly assigned to users.",
+                "properties": {
+                  "type": {
+                    "enum": [
+                      "user_role"
+                    ]
+                  },
+                  "parent_role": {
+                    "allOf": [
+                      {
+                        "$ref": "#/components/schemas/RoleId"
+                      },
+                      {
+                        "description": "Optional parent role that this role inherits from. Must be an `org_role` or a sharing role of type `share_role` or `partner_role`."
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "description": "A role automatically applied to all users in an organization.",
+                "properties": {
+                  "type": {
+                    "enum": [
+                      "org_role"
+                    ]
+                  },
+                  "pricing_tier": {
+                    "type": "string",
+                    "description": "The pricing tier of the organization this root role is based on",
+                    "example": "Professional"
+                  }
+                }
+              },
+              {
+                "description": "A role that can be assigned to users in other organizations for sharing purposes.",
+                "properties": {
+                  "type": {
+                    "enum": [
+                      "share_role"
+                    ]
+                  }
+                }
+              },
+              {
+                "description": "A role that appears in another organization's role list that can be assigned but not modified by the partner organization.",
+                "properties": {
+                  "type": {
+                    "enum": [
+                      "partner_role"
+                    ]
+                  },
+                  "partner_org_id": {
+                    "allOf": [
+                      {
+                        "description": "Partner organization who can assign this role to their users."
+                      },
+                      {
+                        "$ref": "#/components/schemas/OrganizationId"
+                      }
+                    ]
+                  }
+                }
+              },
+              {
+                "description": "A role that is applied to end customers and installers using the Portals",
+                "properties": {
+                  "type": {
+                    "enum": [
+                      "portal_role"
+                    ]
+                  }
+                }
+              }
+            ]
+          }
+        ]
+      },
+      "Error": {
+        "type": "object",
+        "description": "Error response",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Error message",
+            "example": "Parent role 123:nonexistent does not exist"
+          }
+        },
+        "required": [
+          "message"
+        ]
+      }
+    }
+  },
+  "servers": [
+    {
+      "url": "https://permissions.sls.epilot.io"
+    }
+  ]
+}