{ "openapi": "3.0.3", "info": { "title": "Permissions API", "version": "1.2.1", "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" }, { "$ref": "#/components/schemas/EqualsCurrentUserCondition" } ] } ] }, "EqualsCurrentUserCondition": { "description": "Check if any relation_user attribute on the entity contains the current user. When attribute is provided, only that specific attribute path is checked.", "type": "object", "properties": { "attribute": { "type": "string", "description": "Optional JSON path to a specific user attribute. When omitted, all relation_user attributes on the entity are scanned.", "example": "assignee.*.user_id" }, "operation": { "type": "string", "enum": [ "equals_current_user" ] } }, "required": [ "operation" ] }, "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: :" }, "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`." } ] }, "vendor_created": { "type": "boolean", "description": "Indicates whether this role was created by a vendor organization on behalf of the partner organization." } } } ] }, "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)" }, "vendor_created": { "type": "boolean", "description": "Indicates whether this role was created by a vendor organization on behalf of the partner organization." } } } ] }, "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`." } ] }, "vendor_created": { "type": "boolean", "description": "Indicates whether this role was created by a vendor organization on behalf of the partner organization." } } }, { "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" } ] }, "vendor_created": { "type": "boolean", "description": "Indicates whether this role was created by a vendor organization on behalf of the partner organization." } } }, { "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": [] }