openapi: 3.0.0 info: description: This is the OAS 3.0 specification for the Common API in Sophos Central. version: 1.3.1 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' title: Common API tags: - name: Aggregation Alerts description: >- List open alerts, search alerts, and perform actions such as resolving alerts. - name: Alerts description: >- List open alerts, search alerts, and perform actions such as resolving alerts. - name: Directory Management description: Manage users and groups in the directory. - name: Tenant role management description: Central role management API for Tenants. - name: tenant-access description: Manage tenant access and permissions. servers: - url: 'https://api-{dataRegion}.central.sophos.com/common/v1' description: Regional service in the production environment. variables: dataRegion: description: Data region where tenant data is stored. default: eu01 enum: - eu01 - eu02 - us01 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 security: - bearerAuth: [] paths: /admins: get: x-soph-permissions: 'tenant-admin:list AND assignment:read' summary: List all admins description: List all tenant admins. operationId: listTenantAdmins tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' examples: OneFieldDefaultSort: value: - lastSeenAt OneFieldSort: value: - 'lastSeenAt:asc' MoreThanOneTermSort: value: - 'lastSeenAt:asc' - 'hostname:desc' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: search description: Search for items that match the given terms. required: false schema: type: string example: john - in: query name: searchFields description: >- Search only within the specified fields, username field is default if search query is specified. required: false style: form explode: false schema: type: array items: description: Admin fields applicable for search. type: string format: enum enum: - username example: username - in: query name: roleId description: Role ID to search. required: false schema: type: string format: uuid example: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: Size of the page requested. required: false schema: type: integer default: 50 maximum: 100 minimum: 1 example: 50 responses: '200': description: Paged array of tenant admins. content: application/json: schema: type: object description: Page of tenant admins. required: - items - pages properties: items: description: Page of tenant admins. type: array items: type: object description: Tenant admin. required: - id - tenant - users - profile - roleAssignments properties: id: description: Admin UUID. type: string format: uuid tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string users: description: >- List of directory users with which admin is associated by email. type: array uniqueItems: true items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. profile: type: object description: Admin profile with personal details. required: - name - email properties: name: description: Name of user. type: string firstName: description: First name of user. type: string lastName: description: Last name of user. type: string email: description: Email ID of user. type: string format: email readOnly: true roleAssignments: description: List of role assignments. type: array uniqueItems: true items: type: object description: Role assignment. required: - id - roleId properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role UUID. type: string format: uuid createdAt: description: Date and time the tenant admin was created. type: string format: datetime updatedAt: description: Date and time the tenant admin was last updated. type: string format: datetime pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. example: items: - id: e1c7aa85-7863-4561-a50e-2b345b0e16e5 tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b users: - id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 name: John Smith - id: 95685fcb-8ee1-4fad-96e6-966dd5588025 name: Johnny Smith profile: name: John Smith firstName: John lastName: Smith email: john.smith@example.com roleAssignments: - id: 4bcb8ee6-720b-40c7-b748-716a3c47c185 roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 createdAt: '2021-01-02T15:32:59.789Z' updatedAt: '2021-02-12T20:00:01.329Z' - id: e7f8d6de-5030-4e5b-a07a-b01865642afb tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b users: - id: 17ee9fd4-ec71-4b07-8c8a-bfbf9391e1dc name: Fred Bloggs profile: name: Freddie Bloggs firstName: Fred lastName: Bloggs email: flogs@example.com roleAssignments: - id: 95105bd1-b96f-4f77-b220-57f00a43b1ef roleId: fd160a43-87e4-4334-8732-4de1bc9202d8 createdAt: '2021-01-03T10:45:01.492Z' updatedAt: '2021-02-12T18:28:42.004Z' '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b post: x-soph-permissions: 'tenant-admin:create' summary: Create new admin description: Create a tenant admin from a directory user. operationId: createTenantAdmin tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string requestBody: description: New admin creation request. required: true content: application/json: schema: type: object description: Create a tenant admin from a directory user. required: - userId - roleAssignments properties: userId: description: User UUID. type: string format: uuid roleAssignments: description: Role assignments. type: array items: type: object description: Request object to create new role assignment. required: - roleId properties: roleId: description: Role UUID. type: string format: uuid maxItems: 1 minItems: 1 example: userId: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 roleAssignments: - roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 responses: '201': description: Requested admin created. content: application/json: schema: type: object description: Tenant admin. required: - id - tenant - users - profile - roleAssignments properties: id: description: Admin UUID. type: string format: uuid tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string users: description: >- List of directory users with which admin is associated by email. type: array uniqueItems: true items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. profile: type: object description: Admin profile with personal details. required: - name - email properties: name: description: Name of user. type: string firstName: description: First name of user. type: string lastName: description: Last name of user. type: string email: description: Email ID of user. type: string format: email readOnly: true roleAssignments: description: List of role assignments. type: array uniqueItems: true items: type: object description: Role assignment. required: - id - roleId properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role UUID. type: string format: uuid createdAt: description: Date and time the tenant admin was created. type: string format: datetime updatedAt: description: Date and time the tenant admin was last updated. type: string format: datetime example: id: e1c7aa85-7863-4561-a50e-2b345b0e16e5 tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b users: - id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 name: John Smith - id: 95685fcb-8ee1-4fad-96e6-966dd5588025 name: Johnny Smith profile: name: John Smith firstName: John lastName: Smith email: john.smith@example.com roleAssignments: - id: 4bcb8ee6-720b-40c7-b748-716a3c47c185 roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 createdAt: '2021-01-02T15:32:59.789Z' updatedAt: '2021-02-12T20:00:01.329Z' '404': description: Can't find user ID or role ID passed as part of admin creation. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: notFound message: Resource not found. correlationId: bc0047d4-9aad-4501-8c4d-fb9ed8436d39 requestId: 9ec0a3cd-0cd7-4e60-a218-f469a46c1577 '409': description: >- An administrator with the same details already exists in this or another tenant. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: resourceConflict message: Resource conflict. correlationId: da494ea1-ad61-4371-9b77-d8e68c484b95 requestId: 3526d1e5-2996-4245-98ff-81226da03c56 '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b '/admins/{adminId}': get: x-soph-permissions: 'tenant-admin:read AND assignment:read' summary: Get admin by ID description: Get tenant admin details by ID. operationId: getTenantAdminById tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: adminId description: Admin ID. required: true schema: type: string format: uuid example: e1c7aa85-7863-4561-a50e-2b345b0e16e5 responses: '200': description: Details of the requested tenant admin. content: application/json: schema: type: object description: Tenant admin. required: - id - tenant - users - profile - roleAssignments properties: id: description: Admin UUID. type: string format: uuid tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string users: description: >- List of directory users with which admin is associated by email. type: array uniqueItems: true items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. profile: type: object description: Admin profile with personal details. required: - name - email properties: name: description: Name of user. type: string firstName: description: First name of user. type: string lastName: description: Last name of user. type: string email: description: Email ID of user. type: string format: email readOnly: true roleAssignments: description: List of role assignments. type: array uniqueItems: true items: type: object description: Role assignment. required: - id - roleId properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role UUID. type: string format: uuid createdAt: description: Date and time the tenant admin was created. type: string format: datetime updatedAt: description: Date and time the tenant admin was last updated. type: string format: datetime example: id: e1c7aa85-7863-4561-a50e-2b345b0e16e5 tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b users: - id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 name: John Smith - id: 95685fcb-8ee1-4fad-96e6-966dd5588025 name: Johnny Smith profile: name: John Smith firstName: John lastName: Smith email: john.smith@example.com roleAssignments: - id: 4bcb8ee6-720b-40c7-b748-716a3c47c185 roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 createdAt: '2021-01-02T15:32:59.789Z' updatedAt: '2021-02-12T20:00:01.329Z' '404': description: Can't find admin. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: notFound message: Resource not found. correlationId: bc0047d4-9aad-4501-8c4d-fb9ed8436d39 requestId: 9ec0a3cd-0cd7-4e60-a218-f469a46c1577 '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b delete: x-soph-permissions: 'tenant-admin:delete' summary: Remove an admin description: Remove an admin by ID. operationId: deprovisionAdminById tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: adminId description: Admin ID. required: true schema: type: string format: uuid example: e1c7aa85-7863-4561-a50e-2b345b0e16e5 responses: '200': description: Requested admin already removed. content: application/json: schema: type: object description: Response to a previous request to delete an item. required: - deleted properties: deleted: type: boolean example: deleted: true '404': description: Can't find admin. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: notFound message: Resource not found. correlationId: bc0047d4-9aad-4501-8c4d-fb9ed8436d39 requestId: 9ec0a3cd-0cd7-4e60-a218-f469a46c1577 '409': description: Can't remove last Super admin. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: resourceConflict message: Resource conflict. correlationId: da494ea1-ad61-4371-9b77-d8e68c484b95 requestId: 3526d1e5-2996-4245-98ff-81226da03c56 '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b '/admins/{adminId}/role-assignments': get: x-soph-permissions: 'assignment:read' summary: List all roles description: Get the list of role assignments for given admin. operationId: listAdminRoleAssignments tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: adminId description: Admin ID. required: true schema: type: string format: uuid example: e1c7aa85-7863-4561-a50e-2b345b0e16e5 responses: '200': description: List of role assignments for an admin. content: application/json: schema: type: object description: List of role assignments. required: - items properties: items: description: List of role assignments. type: array items: type: object description: Role assignment. required: - id - roleId properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role UUID. type: string format: uuid uniqueItems: true example: items: - id: 4bcb8ee6-720b-40c7-b748-716a3c47c185 roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 - id: c4af6827-06c1-46d3-a4d3-cc937ff02e46 roleId: 4b357587-a78b-4883-aff8-99bdd308b7b6 - id: 3d469dbb-93c5-45e3-bbcf-8881e56f18c4 roleId: ec813884-2570-444b-a1fc-956940a69ce0 '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b post: x-soph-permissions: 'assignment:create' summary: Assign a role description: >- Assign a role of principal type "user" to a tenant admin. Any existing assignment is overridden. operationId: createAdminRoleAssignment tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: adminId description: Admin ID. required: true schema: type: string format: uuid example: e1c7aa85-7863-4561-a50e-2b345b0e16e5 requestBody: description: New role assignment request. required: true content: application/json: schema: type: object description: Request object to create new role assignment. required: - roleId properties: roleId: description: Role UUID. type: string format: uuid example: roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 responses: '201': description: Requested assignment created. content: application/json: schema: type: object description: Role assignment. required: - id - roleId properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role UUID. type: string format: uuid example: id: 4bcb8ee6-720b-40c7-b748-716a3c47c185 roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 '404': description: Can't find admin or role. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: notFound message: Resource not found. correlationId: bc0047d4-9aad-4501-8c4d-fb9ed8436d39 requestId: 9ec0a3cd-0cd7-4e60-a218-f469a46c1577 '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b '/admins/{adminId}/role-assignments/{assignmentId}': get: x-soph-permissions: 'assignment:read' summary: Get role by ID description: Get tenant admin role assignment by ID. operationId: getAdminRoleAssignmentById tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: adminId description: Admin ID. required: true schema: type: string format: uuid example: e1c7aa85-7863-4561-a50e-2b345b0e16e5 - in: path name: assignmentId description: Role Assignment ID. required: true schema: type: string format: uuid example: 4bcb8ee6-720b-40c7-b748-716a3c47c185 responses: '200': description: Details of role assignment. content: application/json: schema: type: object description: Role assignment. required: - id - roleId properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role UUID. type: string format: uuid example: id: 4bcb8ee6-720b-40c7-b748-716a3c47c185 roleId: c83c9481-f63c-4eb8-8793-e81eb9d66ef4 '404': description: Can't find admin or assignment. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: notFound message: Resource not found. correlationId: bc0047d4-9aad-4501-8c4d-fb9ed8436d39 requestId: 9ec0a3cd-0cd7-4e60-a218-f469a46c1577 '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b delete: x-soph-permissions: 'assignment:delete' summary: Remove a role description: Remove role assignment from an admin. operationId: removeAdminRoleAssignmentById tags: - tenant-access - admins parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: adminId description: Admin ID. required: true schema: type: string format: uuid example: e1c7aa85-7863-4561-a50e-2b345b0e16e5 - in: path name: assignmentId description: Role Assignment ID. required: true schema: type: string format: uuid example: 4bcb8ee6-720b-40c7-b748-716a3c47c185 responses: '200': description: Role assignment removed. content: application/json: schema: type: object description: Response to a previous request to delete an item. required: - deleted properties: deleted: type: boolean example: deleted: true '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b /alerts: get: summary: Query alerts description: Get alerts matching criteria in query parameters. x-soph-permissions: 'alerts:read' operationId: getAlerts tags: - Alerts parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: groupKey description: Alert group key. You can filter by group key. schema: type: string example: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs - in: query name: from description: You can find alerts that were raised on or after this time. schema: type: string format: datetime example: '2021-02-12T10:00:00.000Z' - in: query name: to description: You can find alerts that were raised before this time. schema: type: string format: datetime example: '2021-02-13T10:00:00.000Z' - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:([aA]|[dD][eE])[sS][cC]$)' - in: query name: product description: Alerts for a product. You can query by product types. style: form explode: false schema: type: array items: type: string description: Product types. enum: - other - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - ztna - cswitch - secureWebservice example: 'endpoint,server,wireless' - in: query name: category description: Alert category. You can query by different categories. style: form explode: false schema: type: array items: type: string description: Alert categories. enum: - adSync - applicationControl - appReputation - azure - blockListed - connectivity - credentialManager - criticalAttackWarning - cswitch - cwg - denc - deviceAndPlatformHealth - dnsProtectionLocation - downloadReputation - endpointFirewall - fenc - forensicSnapshot - general - integrations - isolation - malware - mobiles - mtr - policy - protection - pua - runtimeDetections - security - smc - systemHealth - uav - uncategorized - updating - utm - virt - wireless - xgEmail - ztnaAuthentication - ztnaGateway - ztnaResource example: 'applicationControl,runtimeDetections,security' - in: query name: severity description: >- Alerts for a specific severity level. You can query by severity levels. style: form explode: false schema: type: array items: type: string description: Severity levels for alerts. enum: - high - medium - low example: 'high,medium' - in: query name: ids description: List of IDs. style: form explode: false schema: type: array items: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageFromKey required: false schema: type: string description: The key of the item from where to fetch a page. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. responses: '200': headers: Last-Modified: schema: type: string format: date-time description: Page of alerts. content: application/json: schema: type: object description: Page of alerts. required: - items - pages properties: items: type: array description: List of alerts. items: type: object description: Alert object. required: - id properties: id: description: Alert ID. type: string format: uuid allowedActions: description: Actions that you can perform on these alerts. type: array items: type: string description: Actions that you can perform on these alerts. enum: - acknowledge - cleanPua - cleanVirus - authPua - clearThreat - clearHmpa - sendMsgPua - sendMsgThreat category: type: string description: Alert categories. enum: - adSync - applicationControl - appReputation - azure - blockListed - connectivity - credentialManager - criticalAttackWarning - cswitch - cwg - denc - deviceAndPlatformHealth - dnsProtectionLocation - downloadReputation - endpointFirewall - fenc - forensicSnapshot - general - integrations - isolation - malware - mobiles - mtr - policy - protection - pua - runtimeDetections - security - smc - systemHealth - uav - uncategorized - updating - utm - virt - wireless - xgEmail - ztnaAuthentication - ztnaGateway - ztnaResource description: description: Alert description. type: string groupKey: description: Alert group key. type: string managedAgent: type: object required: - id - type properties: id: description: Alert source ID. type: string format: uuid type: type: string description: Source that triggered the alert. enum: - mobile - computer - server - securityVm - utm - accessPoint - wirelessNetwork - mailbox - slec - xgFirewall - ztnaGateway - sensor name: type: string description: Name of alert source. person: type: object description: >- Reference to the associated person on the alert source. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User name. product: type: string description: Product types. enum: - other - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - ztna - cswitch - secureWebservice raisedAt: description: When the alert was triggered. type: string format: datetime severity: type: string description: Severity levels for alerts. enum: - high - medium - low tenant: type: object required: - id - name properties: id: description: Tenant ID for the alert. type: string format: uuid name: description: Tenant name. type: string dataRegion: type: string description: The data region where tenant data is stored. enum: - eu01 - eu02 - us01 - us02 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 type: description: Alert type. type: string maxItems: 100 pages: type: object required: - maxSize - size properties: fromKey: type: string description: The key of the first item in the returned page. nextKey: type: string description: The key to use when fetching the next page. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: >- (Optional) The total number of items on all the pages, if pageTotal=true was passed into the request. maxSize: type: integer description: The maximum page size that can be requested. example: items: - id: a5ded91c-6575-435c-a6b4-64b94f9048ff allowedActions: - acknowledge category: updating description: John-PC is out of date. groupKey: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs managedAgent: id: bb90527d-73a8-4e6e-85c6-20c2e0c5bc6f type: computer person: id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 product: endpoint raisedAt: '2021-02-12T15:04:53.780' severity: medium tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b name: Acme Corp type: 'Event::Endpoint::OutOfDate' lastCorrelatedAt: '2021-02-12T16:30:45.123Z' updatedAt: '2021-02-12T16:30:45.123Z' eventCount: 5 status: open - id: f9415c5f-e0e9-41d7-8126-1956223a66f1 allowedActions: - acknowledge - cleanPua category: updating description: 'Generic reputation PUA detected C:\Temp\WinExeSvc.exe' groupKey: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs managedAgent: id: bb90527d-73a8-4e6e-85c6-20c2e0c5bc6f type: computer person: id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 product: endpoint raisedAt: '2021-02-12T15:04:53.780' severity: medium tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b name: Acme Corp type: 'Event::Endpoint::PUADetected' lastCorrelatedAt: '2021-02-12T15:04:53.780Z' updatedAt: '2021-02-12T15:04:53.780Z' eventCount: 1 status: open pages: nextKey: '2000818931339' total: 1 items: 2 size: 50 maxSize: 1000 '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b /alerts/search: post: summary: Query alerts (POST) description: Get alerts matching request. x-soph-permissions: 'alerts:read' operationId: getAlertsThroughPost tags: - Alerts parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: groupKey description: Alert group key. You can filter by group key. schema: type: string example: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs - in: query name: from description: You can find alerts that were raised on or after this time. schema: type: string format: datetime example: '2021-02-12T10:00:00.000Z' - in: query name: to description: You can find alerts that were raised before this time. schema: type: string format: datetime example: '2021-02-13T10:00:00.000Z' - in: query name: sort description: Defines how to sort the data. style: form explode: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:([aA]|[dD][eE])[sS][cC]$)' - in: query name: product description: Alerts for a product. You can query by product types. style: form explode: false schema: type: array items: type: string description: Product types. enum: - other - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - ztna - cswitch - secureWebservice example: 'endpoint,server,wireless' - in: query name: category description: Alert category. You can query by different categories. style: form explode: false schema: type: array items: type: string description: Alert categories. enum: - adSync - applicationControl - appReputation - azure - blockListed - connectivity - credentialManager - criticalAttackWarning - cswitch - cwg - denc - deviceAndPlatformHealth - dnsProtectionLocation - downloadReputation - endpointFirewall - fenc - forensicSnapshot - general - integrations - isolation - malware - mobiles - mtr - policy - protection - pua - runtimeDetections - security - smc - systemHealth - uav - uncategorized - updating - utm - virt - wireless - xgEmail - ztnaAuthentication - ztnaGateway - ztnaResource example: 'applicationControl,runtimeDetections,security' - in: query name: severity description: >- Alerts for a specific severity level. You can query by severity levels. style: form explode: false schema: type: array items: type: string description: Severity levels for alerts. enum: - high - medium - low example: 'high,medium' - in: query name: ids description: List of IDs. style: form explode: false schema: type: array items: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageFromKey required: false schema: type: string description: The key of the item from where to fetch a page. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. requestBody: required: true content: application/json: schema: type: object description: Response to a previous request to act on a specific alert. properties: category: description: Alert category. type: array items: type: string description: Alert categories. enum: - adSync - applicationControl - appReputation - azure - blockListed - connectivity - credentialManager - criticalAttackWarning - cswitch - cwg - denc - deviceAndPlatformHealth - dnsProtectionLocation - downloadReputation - endpointFirewall - fenc - forensicSnapshot - general - integrations - isolation - malware - mobiles - mtr - policy - protection - pua - runtimeDetections - security - smc - systemHealth - uav - uncategorized - updating - utm - virt - wireless - xgEmail - ztnaAuthentication - ztnaGateway - ztnaResource groupKey: description: Alert group key. type: string fields: description: Fields to return in a partial response. type: array items: type: string from: description: You can find alerts that were raised on or after this time. type: string format: datetime ids: description: Alert IDs. type: array items: type: string format: uuid product: description: Product that triggered the alert. type: array items: type: string description: Product types. enum: - other - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - ztna - cswitch - secureWebservice severity: description: Severity level of the alert. type: array items: type: string description: Severity levels for alerts. enum: - high - medium - low to: description: You can find alerts that were raised before this time. type: string format: datetime pageFromKey: type: string description: Key of the item from where to fetch a page. pageSize: type: integer description: Size of the page requested. pageTotal: type: boolean description: >- Whether the number of pages should be calculated and returned in the response. sort: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' example: category: - malware - mobiles - policy - protection fields: - severity - groupKey - allowedActions from: '2021-02-12T10:00:00.000Z' groupKey: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs ids: - 533a799a-9914-4a6f-ae4c-45cb36fa3672 - 8c26a3db-9a72-45be-8bfa-1e032209a50b - 6289af43-ba34-4b59-b3de-23c90fbe9080 pageFromKey: '2000818931339' pageSize: 50 pageTotal: true product: - mobile - wireless - endpoint severity: - high - medium sort: - 'raisedAt:desc' to: '2021-02-13T10:00:00.000Z' status: - open - closed action: - acknowledge managedAgentNameContains: server personNameContains: john search: malware searchFields: - personName - managedAgentName locale: en-US updatedFrom: '2021-02-01T00:00:00.000Z' updatedTo: '2021-02-28T23:59:59.999Z' type: - 'Event::Endpoint::Malware::Detection' severityFilterMode: exact responses: '200': headers: Last-Modified: schema: type: string format: date-time description: Page of alerts. content: application/json: schema: type: object description: Page of alerts. required: - items - pages properties: items: type: array description: List of alerts. items: type: object description: Alert object. required: - id properties: id: description: Alert ID. type: string format: uuid allowedActions: description: Actions that you can perform on these alerts. type: array items: type: string description: Actions that you can perform on these alerts. enum: - acknowledge - cleanPua - cleanVirus - authPua - clearThreat - clearHmpa - sendMsgPua - sendMsgThreat category: type: string description: Alert categories. enum: - adSync - applicationControl - appReputation - azure - blockListed - connectivity - credentialManager - criticalAttackWarning - cswitch - cwg - denc - deviceAndPlatformHealth - dnsProtectionLocation - downloadReputation - endpointFirewall - fenc - forensicSnapshot - general - integrations - isolation - malware - mobiles - mtr - policy - protection - pua - runtimeDetections - security - smc - systemHealth - uav - uncategorized - updating - utm - virt - wireless - xgEmail - ztnaAuthentication - ztnaGateway - ztnaResource description: description: Alert description. type: string groupKey: description: Alert group key. type: string managedAgent: type: object required: - id - type properties: id: description: Alert source ID. type: string format: uuid type: type: string description: Source that triggered the alert. enum: - mobile - computer - server - securityVm - utm - accessPoint - wirelessNetwork - mailbox - slec - xgFirewall - ztnaGateway - sensor name: type: string description: Name of alert source. person: type: object description: >- Reference to the associated person on the alert source. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User name. product: type: string description: Product types. enum: - other - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - ztna - cswitch - secureWebservice raisedAt: description: When the alert was triggered. type: string format: datetime severity: type: string description: Severity levels for alerts. enum: - high - medium - low tenant: type: object required: - id - name properties: id: description: Tenant ID for the alert. type: string format: uuid name: description: Tenant name. type: string dataRegion: type: string description: The data region where tenant data is stored. enum: - eu01 - eu02 - us01 - us02 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 type: description: Alert type. type: string maxItems: 100 pages: type: object required: - maxSize - size properties: fromKey: type: string description: The key of the first item in the returned page. nextKey: type: string description: The key to use when fetching the next page. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: >- (Optional) The total number of items on all the pages, if pageTotal=true was passed into the request. maxSize: type: integer description: The maximum page size that can be requested. example: items: - id: a5ded91c-6575-435c-a6b4-64b94f9048ff allowedActions: - acknowledge category: updating description: John-PC is out of date. groupKey: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs managedAgent: id: bb90527d-73a8-4e6e-85c6-20c2e0c5bc6f type: computer person: id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 product: endpoint raisedAt: '2021-02-12T15:04:53.780' severity: medium tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b name: Acme Corp type: 'Event::Endpoint::OutOfDate' lastCorrelatedAt: '2021-02-12T16:30:45.123Z' updatedAt: '2021-02-12T16:30:45.123Z' eventCount: 5 status: open - id: f9415c5f-e0e9-41d7-8126-1956223a66f1 allowedActions: - acknowledge - cleanPua category: updating description: 'Generic reputation PUA detected C:\Temp\WinExeSvc.exe' groupKey: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs managedAgent: id: bb90527d-73a8-4e6e-85c6-20c2e0c5bc6f type: computer person: id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 product: endpoint raisedAt: '2021-02-12T15:04:53.780' severity: medium tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b name: Acme Corp type: 'Event::Endpoint::PUADetected' lastCorrelatedAt: '2021-02-12T15:04:53.780Z' updatedAt: '2021-02-12T15:04:53.780Z' eventCount: 1 status: open pages: nextKey: '2000818931339' total: 1 items: 2 size: 50 maxSize: 1000 '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b '/alerts/{alertId}': get: summary: Get alert details description: Get details of a specific alert. x-soph-permissions: 'alerts:read' operationId: getAlertById tags: - Alerts parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: alertId description: Alert ID. required: true schema: type: string format: uuid example: a5ded91c-6575-435c-a6b4-64b94f9048ff responses: '200': description: Details of the requested alert. content: application/json: schema: type: object description: Alert object. required: - id properties: id: description: Alert ID. type: string format: uuid allowedActions: description: Actions that you can perform on these alerts. type: array items: type: string description: Actions that you can perform on these alerts. enum: - acknowledge - cleanPua - cleanVirus - authPua - clearThreat - clearHmpa - sendMsgPua - sendMsgThreat category: type: string description: Alert categories. enum: - adSync - applicationControl - appReputation - azure - blockListed - connectivity - credentialManager - criticalAttackWarning - cswitch - cwg - denc - deviceAndPlatformHealth - dnsProtectionLocation - downloadReputation - endpointFirewall - fenc - forensicSnapshot - general - integrations - isolation - malware - mobiles - mtr - policy - protection - pua - runtimeDetections - security - smc - systemHealth - uav - uncategorized - updating - utm - virt - wireless - xgEmail - ztnaAuthentication - ztnaGateway - ztnaResource description: description: Alert description. type: string groupKey: description: Alert group key. type: string managedAgent: type: object required: - id - type properties: id: description: Alert source ID. type: string format: uuid type: type: string description: Source that triggered the alert. enum: - mobile - computer - server - securityVm - utm - accessPoint - wirelessNetwork - mailbox - slec - xgFirewall - ztnaGateway - sensor name: type: string description: Name of alert source. person: type: object description: Reference to the associated person on the alert source. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User name. product: type: string description: Product types. enum: - other - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - ztna - cswitch - secureWebservice raisedAt: description: When the alert was triggered. type: string format: datetime severity: type: string description: Severity levels for alerts. enum: - high - medium - low tenant: type: object required: - id - name properties: id: description: Tenant ID for the alert. type: string format: uuid name: description: Tenant name. type: string dataRegion: type: string description: The data region where tenant data is stored. enum: - eu01 - eu02 - us01 - us02 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 type: description: Alert type. type: string example: id: a5ded91c-6575-435c-a6b4-64b94f9048ff allowedActions: - acknowledge category: updating description: John-PC is out of date. groupKey: MSxFdmVudDo6RW5kcG9pbnQ6Ok91dE9mRGF0ZSw1MTMs managedAgent: id: bb90527d-73a8-4e6e-85c6-20c2e0c5bc6f type: computer person: id: 17dd896f-ee9f-4f7d-a2a2-6a8c0b48ff15 product: endpoint raisedAt: '2021-02-12T15:04:53.780' severity: medium tenant: id: 79067fa3-e4d0-4769-a5f7-8d6550b3b68b name: Acme Corp type: 'Event::Endpoint::OutOfDate' lastCorrelatedAt: '2024-02-12T16:30:45.123Z' updatedAt: '2024-02-12T16:30:45.123Z' eventCount: 5 status: open '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b '/alerts/{alertId}/actions': post: summary: Act on alert description: Take an action on a specific alert. operationId: takeAlertActions x-soph-permissions: 'alerts:action' tags: - Alerts parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: alertId description: Alert ID. required: true schema: type: string format: uuid example: a5ded91c-6575-435c-a6b4-64b94f9048ff requestBody: required: true content: application/json: schema: type: object description: Request to perform a specified action on the selected alerts. required: - action properties: action: type: string description: Actions that you can perform on these alerts. enum: - acknowledge - cleanPua - cleanVirus - authPua - clearThreat - clearHmpa - sendMsgPua - sendMsgThreat message: description: Message to send for the action. type: string example: action: cleanPua message: Remove WinExeSvc responses: '201': description: Action has been successfully completed for the alert. content: application/json: schema: type: object description: Response to a previous request to act on a specific alert. required: - id - alertId - action - status - requestedAt properties: id: description: Alert action ID. type: string format: uuid alertId: description: Alert ID. type: string format: uuid action: type: string description: Actions that you can perform on these alerts. enum: - acknowledge - cleanPua - cleanVirus - authPua - clearThreat - clearHmpa - sendMsgPua - sendMsgThreat status: type: string description: Status of an alert action. enum: - requested - started - completed requestedAt: description: Time when the action was requested. type: string format: datetime completedAt: description: Time when the action was completed. type: string format: datetime startedAt: description: Time when the action was started. type: string format: datetime result: description: Result of the action. type: string example: id: 2f2d0c43-5687-4cf6-ba15-dd1c1173e673 alertId: f9415c5f-e0e9-41d7-8126-1956223a66f1 action: cleanPua status: started requestedAt: '2021-02-12T14:35:20.248' startedAt: '2021-02-12T14:37:01.922' completedAt: null result: '' '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri example: error: internalServerError message: Internal Server Error. correlationId: df88bf88-471b-49d6-8a5e-07a26964d2ec requestId: 85073630-8ad8-46da-bf64-cb1e8b6f864b /directory/users: get: x-soph-permissions: 'tenant-directory.user:read' summary: Query users description: List users in the directory. operationId: listTenantUsers tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: sort description: >- Comma-separated list of sort criteria for users. Valid sort fields are `id`, `name`, `firstName`, `lastName`, `email`, `exchangeLogin`, `createdAt`, and `updatedAt`. You can append ':asc' or ':desc' to each field to specify the sort direction. The default sort direction for each field is unspecified. style: form explode: false required: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: Size of the page requested. required: false schema: type: integer default: 50 maximum: 100 minimum: 1 - in: query name: ids description: List of item IDs to match. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 - in: query name: search description: Search for items that match the given terms. required: false schema: type: string - in: query name: searchFields description: >- Search only within the specified fields. When not specified, the default behavior is to search the full names of users, only. required: false style: form explode: false schema: type: array items: description: User fields that you can search. type: string format: enum enum: - name - firstName - lastName - email - exchangeLogin - in: query name: sourceType description: Source directory type. required: false schema: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory - in: query name: groupId description: Search for users in a group that has this ID. required: false schema: type: string format: uuid - in: query name: domain description: List the items that match the given domain. required: false schema: type: string responses: '200': description: Page of users. content: application/json: schema: type: object description: Page of users. required: - items - pages properties: items: type: array items: type: object description: User in the directory. required: - id - name - source - tenant properties: id: description: User ID. type: string format: uuid name: description: User's name. type: string firstName: description: User's first name or given name. type: string lastName: description: User's last name or surname. type: string email: description: User's email address. type: string domain: description: Domain name. type: string exchangeLogin: description: User's Exchange login. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory createdAt: description: When the user was created. type: string format: datetime updatedAt: description: When the user was last updated. type: string format: datetime manager: type: object description: Manager in the directory. properties: id: type: string format: uuid description: Manager ID. name: type: string description: Manager name. pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'tenant-directory.user:create AND tenant-directory.membership:add' summary: Add new user description: Add a new user to the directory. operationId: createTenantUser tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string requestBody: description: New user request. required: true content: application/json: schema: type: object description: Request to add a new user to the directory. required: - name properties: name: description: User's full name. type: string minLength: 1 maxLength: 250 firstName: description: >- User's first name or given name. This must not include a space. type: string maxLength: 250 lastName: description: User's last name or surname. type: string maxLength: 250 email: description: User's email address. type: string format: email exchangeLogin: description: User's Exchange login. type: string maxLength: 350 groupIds: description: Groups that the user should be added to. type: array items: type: string format: uuid uniqueItems: true maxItems: 50 managerId: description: Manager in the directory to whom the current user reports. type: string format: uuid example: name: John Doe firstName: John lastName: Doe email: jonhdoe@example.com exchangeLogin: exchangeLogin groupIds: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 managerId: 77899dfe-38ed-417d-bc9d-2ef832e6ae4f responses: '201': description: A new user was added to the directory. content: application/json: schema: type: object description: User in the directory. required: - id - name - source - tenant properties: id: description: User ID. type: string format: uuid name: description: User's name. type: string firstName: description: User's first name or given name. type: string lastName: description: User's last name or surname. type: string email: description: User's email address. type: string domain: description: Domain name. type: string exchangeLogin: description: User's Exchange login. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory createdAt: description: When the user was created. type: string format: datetime updatedAt: description: When the user was last updated. type: string format: datetime manager: type: object description: Manager in the directory. properties: id: type: string format: uuid description: Manager ID. name: type: string description: Manager name. '404': description: >- Can't find at least one group in the request or Manager not found with given ID. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Email address must not already be in use. You also can't use this API to add users to a group synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/directory/users/{userId}': get: x-soph-permissions: 'tenant-directory.user:read' summary: Get user description: Get a user by ID. operationId: getTenantUserById tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: userId description: User ID. required: true schema: type: string format: uuid responses: '200': description: User. content: application/json: schema: type: object description: User in the directory. required: - id - name - source - tenant properties: id: description: User ID. type: string format: uuid name: description: User's name. type: string firstName: description: User's first name or given name. type: string lastName: description: User's last name or surname. type: string email: description: User's email address. type: string domain: description: Domain name. type: string exchangeLogin: description: User's Exchange login. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory createdAt: description: When the user was created. type: string format: datetime updatedAt: description: When the user was last updated. type: string format: datetime manager: type: object description: Manager in the directory. properties: id: type: string format: uuid description: Manager ID. name: type: string description: Manager name. '404': description: Can't find user. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'tenant-directory.user:delete AND tenant-directory.membership:remove' summary: Delete user description: Delete a user by ID. operationId: deleteTenantUserById tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: userId description: User ID. required: true schema: type: string format: uuid responses: '200': description: User deleted or can't find user. content: application/json: schema: type: object description: Response to a previous request to delete an item. required: - deleted properties: deleted: type: boolean '409': description: You can't use this API to delete users synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'tenant-directory.user:update' summary: Update user description: Update an existing user. operationId: patchTenantUser tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: userId description: User ID. required: true schema: type: string format: uuid requestBody: description: Patch object to update the user. required: true content: application/json: schema: type: object description: Request to update a user. properties: name: description: User's full name. type: string minLength: 1 maxLength: 250 firstName: description: >- User's first name or given name. This must not contain a space. type: string maxLength: 250 lastName: description: User's last name or surname. type: string maxLength: 250 email: description: >- User's email address. WARNING: Any Sophos Central administrator using the previous email address as their username won't be able to sign in after this change. type: string nullable: true exchangeLogin: description: User's Exchange login (max 350 characters). type: string nullable: true managerId: description: >- Manager in the directory to whom the current user reports. A user can be the manager of themselves. type: string format: uuid nullable: true example: name: John Doe firstName: John lastName: Doe email: jonhdoe@example.com exchangeLogin: exchangeLogin managerId: 77899dfe-38ed-417d-bc9d-2ef832e6ae4f responses: '200': description: Updated user. content: application/json: schema: type: object description: User in the directory. required: - id - name - source - tenant properties: id: description: User ID. type: string format: uuid name: description: User's name. type: string firstName: description: User's first name or given name. type: string lastName: description: User's last name or surname. type: string email: description: User's email address. type: string domain: description: Domain name. type: string exchangeLogin: description: User's Exchange login. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory createdAt: description: When the user was created. type: string format: datetime updatedAt: description: When the user was last updated. type: string format: datetime manager: type: object description: Manager in the directory. properties: id: type: string format: uuid description: Manager ID. name: type: string description: Manager name. '404': description: User or Manager not found with given ID. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Email address must not already be in use. You can't remove the email address from an admin who uses it to login to Sophos Central Admin. Additionally, you can't use this API to update a user synced from Active Directory or add a user to a group synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /directory/user-groups: get: x-soph-permissions: 'tenant-directory.user-group:read' summary: Query groups description: List groups in the directory. operationId: listTenantUserGroups tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: sort description: >- Comma-separated list of sort criteria for groups. Valid sort fields are `id`, `name`, `createdAt`, and `updatedAt`. You can append ':asc' or ':desc' to each field to specify the sort direction. The default sort direction for each field is unspecified. style: form explode: false required: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: Size of the page requested. required: false schema: type: integer default: 50 maximum: 100 minimum: 1 - in: query name: ids description: List of item IDs to match. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 - in: query name: search description: Search for items that match the given terms. required: false schema: type: string - in: query name: searchFields description: >- Search only within the specified fields. When not specified, the default behavior is to search group names, only. required: false style: form explode: false schema: type: array items: description: Group fields that you can search. type: string format: enum enum: - name - description - in: query name: sourceType description: Source directory type. required: false schema: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory - in: query name: userId description: Search groups associated with the given user ID. required: false schema: type: string format: uuid - in: query name: parentGroupId description: Search subgroups associated with the given group ID. required: false schema: type: string format: uuid - in: query name: domain description: List the items that match the given domain. required: false schema: type: string responses: '200': description: Page of groups. content: application/json: schema: type: object description: Page of groups. required: - items - pages properties: items: type: array items: type: object description: Group in the directory. required: - id - name - source - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string description: description: Group description. type: string domain: description: Domain name. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory users: type: object description: Associated users. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string createdAt: description: When the group was created. type: string format: datetime updatedAt: description: When the group was last updated. type: string format: datetime pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'tenant-directory.user-group:create AND tenant-directory.membership:add' summary: Add new group description: Add a new group to the directory. operationId: createTenantUserGroup tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string requestBody: description: New group request. required: true content: application/json: schema: type: object description: Request to add a new group to the directory. required: - name properties: name: description: Group name. type: string minLength: 1 maxLength: 250 description: description: Group description. type: string maxLength: 1000 userIds: description: Users in the group. type: array items: type: string format: uuid uniqueItems: true maxItems: 1000 example: name: Sophos Central Group description: Security group for Sophos Central admins userIds: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 responses: '201': description: Group created. content: application/json: schema: type: object description: Group in the directory. required: - id - name - source - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string description: description: Group description. type: string domain: description: Domain name. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory users: type: object description: Associated users. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string createdAt: description: When the group was created. type: string format: datetime updatedAt: description: When the group was last updated. type: string format: datetime '404': description: Can't find at least one user in the request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Group names must be unique. You also can't use this API to add users to a group synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/directory/user-groups/{groupId}': get: x-soph-permissions: 'tenant-directory.user-group:read' summary: Get group description: Get group by ID. operationId: getTenantUserGroupById tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid responses: '200': description: Group. content: application/json: schema: type: object description: Group in the directory. required: - id - name - source - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string description: description: Group description. type: string domain: description: Domain name. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory users: type: object description: Associated users. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string createdAt: description: When the group was created. type: string format: datetime updatedAt: description: When the group was last updated. type: string format: datetime '404': description: Can't find group. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'tenant-directory.user-group:delete' summary: Delete group description: Deletes the specified group. operationId: deleteTenantUserGroupById tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid responses: '200': description: Group deleted. content: application/json: schema: type: object description: Response to a previous request to delete an item. required: - deleted properties: deleted: type: boolean '409': description: >- You can only delete empty groups with no members. You also can't use this API to delete groups synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'tenant-directory.user-group:update' summary: Update group description: Update a group. operationId: patchTenantUserGroup tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid requestBody: description: Patch object to update the group. required: true content: application/json: schema: type: object description: Request to update a group. properties: name: description: New group name. type: string minLength: 1 maxLength: 250 description: description: New group description. type: string maxLength: 1000 example: name: Sophos Central Group description: Security group for Sophos Central admins responses: '200': description: Group updated. content: application/json: schema: type: object description: Group in the directory. required: - id - name - source - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string description: description: Group description. type: string domain: description: Domain name. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory users: type: object description: Associated users. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string createdAt: description: When the group was created. type: string format: datetime updatedAt: description: When the group was last updated. type: string format: datetime '404': description: Group not found with given ID. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- Group names must be unique. You also can't use this API to update groups synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/directory/users/{userId}/groups': get: x-soph-permissions: 'tenant-directory.user-group:read' summary: Groups of user description: List groups that a user belongs to. operationId: listTenantUserGroupsByUserId tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: sort description: >- Comma-separated list of sort criteria for groups. Valid sort fields are `id`, `name`, `createdAt`, and `updatedAt`. You can append ':asc' or ':desc' to each field to specify the sort direction. The default sort direction for each field is unspecified. style: form explode: false required: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: Size of the page requested. required: false schema: type: integer default: 50 maximum: 100 minimum: 1 - in: query name: search description: Search for items that match the given terms. required: false schema: type: string - in: query name: searchFields description: >- Search only within the specified fields. When not specified, the default behavior is to search group names, only. required: false style: form explode: false schema: type: array items: description: Group fields that you can search. type: string format: enum enum: - name - description - in: query name: sourceType description: Source directory type. required: false schema: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory - in: path name: userId description: User ID. required: true schema: type: string format: uuid - in: query name: domain description: List the items that match the given domain. required: false schema: type: string responses: '200': description: Page of groups. content: application/json: schema: type: object description: Page of groups. required: - items - pages properties: items: type: array items: type: object description: Group in the directory. required: - id - name - source - tenant properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string description: description: Group description. type: string domain: description: Domain name. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory users: type: object description: Associated users. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string createdAt: description: When the group was created. type: string format: datetime updatedAt: description: When the group was last updated. type: string format: datetime pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '404': description: Can't find user. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'tenant-directory.membership:add' summary: Add to groups description: Add a user to multiple groups. operationId: addUserToMultipleGroups tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: userId description: User ID. required: true schema: type: string format: uuid requestBody: description: Request to add a user to multiple groups. required: true content: application/json: schema: type: object description: Request to add a user to multiple groups. required: - ids properties: ids: description: List of group IDs. type: array items: type: string format: uuid uniqueItems: true maxItems: 50 example: ids: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 responses: '201': description: User added to the specified groups. content: application/json: schema: type: object description: Groups to which the user was added. properties: addedToGroups: description: List of references to groups to which the user was added. type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string '404': description: Can't find user or at least one group in the request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- You can't modify users synced from Active Directory. You also can't use this API to add users to groups synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'tenant-directory.membership:remove' summary: Remove from groups description: Remove a user from multiple groups. operationId: removeUserFromMultipleGroups tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: userId description: User ID. required: true schema: type: string format: uuid - in: query name: ids description: List of group IDs. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 responses: '200': description: User removed from the specified groups. content: application/json: schema: type: object description: Result of removing a user from multiple groups. properties: removedFromGroups: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string errors: type: object description: Error removing a user from multiple groups. properties: groupsNotFound: type: array items: type: string format: uuid '404': description: Can't find user. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: You can't use this API to update users synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/directory/user-groups/{groupId}/users': get: x-soph-permissions: 'tenant-directory.user:read' summary: Users in group description: List users in the specified group. operationId: listTenantUsersByUserGroupId tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: sort description: >- Comma-separated list of sort criteria for users. Valid sort fields are `id`, `name`, `firstName`, `lastName`, `email`, `exchangeLogin`, `createdAt`, and `updatedAt`. You can append ':asc' or ':desc' to each field to specify the sort direction. The default sort direction for each field is unspecified. style: form explode: false required: false schema: type: array items: type: string pattern: '(^[^:]+$)|(^[^:]+:(asc|desc)$)' - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - in: query name: pageSize description: Size of the page requested. required: false schema: type: integer default: 50 maximum: 100 minimum: 1 - in: query name: search description: Search for items that match the given terms. required: false schema: type: string - in: query name: searchFields description: >- Search only within the specified fields. When not specified, the default behavior is to search the full names of users, only. required: false style: form explode: false schema: type: array items: description: User fields that you can search. type: string format: enum enum: - name - firstName - lastName - email - exchangeLogin - in: query name: sourceType description: Source directory type. required: false schema: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid - in: query name: domain description: List the items that match the given domain. required: false schema: type: string responses: '200': description: Page of users. content: application/json: schema: type: object description: Page of users. required: - items - pages properties: items: type: array items: type: object description: User in the directory. required: - id - name - source - tenant properties: id: description: User ID. type: string format: uuid name: description: User's name. type: string firstName: description: User's first name or given name. type: string lastName: description: User's last name or surname. type: string email: description: User's email address. type: string domain: description: Domain name. type: string exchangeLogin: description: User's Exchange login. type: string groups: type: object description: Associated groups. properties: total: type: integer itemsCount: type: integer items: type: array items: type: object description: Group reference. required: - id properties: id: description: Group ID. type: string format: uuid name: description: Group name. type: string displayName: description: Display name. type: string uniqueItems: true tenant: type: object description: Reference to a tenant. required: - id properties: id: description: Tenant ID. type: string format: uuid name: description: Tenant Name. type: string source: type: object description: Source of directory information. required: - type properties: type: description: >- Types of sources of directory information. All users and groups created using this API have the source type `custom`. All users and groups synchronized from Active Directory, Azure Active Directory or Google Directory have the source type `activeDirectory`, `azureActiveDirectory` or `googleDirectory` respectively. type: string format: enum enum: - custom - activeDirectory - azureActiveDirectory - googleDirectory createdAt: description: When the user was created. type: string format: datetime updatedAt: description: When the user was last updated. type: string format: datetime manager: type: object description: Manager in the directory. properties: id: type: string format: uuid description: Manager ID. name: type: string description: Manager name. pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '404': description: Can't find group. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'tenant-directory.membership:add' summary: Add to group description: Add multiple users to the specified group. operationId: addMultipleUsersToGroup tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid requestBody: description: Request to add multiple users to a group. required: true content: application/json: schema: type: object description: Request to add multiple users to a group. required: - ids properties: ids: description: List of user IDs. type: array items: type: string format: uuid uniqueItems: true maxItems: 1000 example: ids: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 responses: '201': description: Users added to the specified group. content: application/json: schema: type: object description: Users added to the group. properties: addedUsers: description: List of references to users added. type: array items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. '404': description: Can't find group or at least one user in the request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- You can't modify groups synced from Active Directory. You also can't use this API to add users synced from Active Directory to a group. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'tenant-directory.membership:remove' summary: Remove from group description: Remove multiple users from a group. operationId: removeMultipleUsersFromGroup tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid - in: query name: ids description: List of user IDs. required: false style: form explode: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 responses: '200': description: Users removed from group. content: application/json: schema: type: object description: Result of removing multiple users from a group. properties: removedUsers: type: array items: type: object description: Reference to the user. required: - id properties: id: type: string format: uuid description: User ID. name: type: string description: User's full name. errors: type: object description: Error removing multiple users from a group. properties: usersNotFound: type: array items: type: string format: uuid '404': description: Can't find group. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/directory/users/{userId}/groups/{groupId}': delete: x-soph-permissions: 'tenant-directory.membership:remove' summary: Remove from group description: Remove user from a group. operationId: removeUserFromSingleGroup tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: userId description: User ID. required: true schema: type: string format: uuid - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid responses: '200': description: User removed from group. content: application/json: schema: type: object description: Result of removing a user from a group. properties: removed: type: boolean '404': description: Can't find user. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: You can't use this API to modify users synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/directory/user-groups/{groupId}/users/{userId}': delete: x-soph-permissions: 'tenant-directory.membership:remove' summary: Remove from group description: Update a group to remove a user. operationId: removeSingleUserFromGroup tags: - Directory Management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: groupId description: Group ID. required: true schema: type: string format: uuid - in: path name: userId description: User ID. required: true schema: type: string format: uuid responses: '200': description: User removed from group. content: application/json: schema: type: object description: Result of removing a user from a group. properties: removed: type: boolean '404': description: Can't find group. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: >- You can't use this API to modify groups synced from Active Directory. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /roles: get: x-soph-permissions: 'role:read' summary: List all roles description: List all tenant roles. operationId: listTenantRoles tags: - Tenant role management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: type description: Role type. required: false schema: description: Role type. type: string format: enum enum: - predefined - custom - in: query name: principalType description: Principal type of role. required: false schema: description: Principal type of role. type: string format: enum enum: - user - service - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: List of tenant roles. content: application/json: schema: type: object description: List of roles. required: - items properties: items: type: array description: List of roles. items: type: object description: Tenant role. required: - id - name - type - principalType - permissionSets properties: id: description: Role UUID. type: string format: uuid name: description: Role name. type: string description: description: Role Description. type: string type: description: Role type. type: string format: enum enum: - predefined - custom principalType: description: Principal type of role. type: string format: enum enum: - user - service permissionSets: description: List of permission sets. type: array items: type: string uniqueItems: true minItems: 1 createdAt: description: Date and time tenant role was created. type: string format: datetime updatedAt: description: Date and time tenant role was last updated. type: string format: datetime '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'role:write' summary: Create new role description: Create a new tenant role. operationId: createTenantRole tags: - Tenant role management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string requestBody: description: New role creation request. required: true content: application/json: schema: type: object description: New tenant role. required: - name - permissionSets - principalType properties: name: description: Role name. type: string maxLength: 100 description: description: Role description. type: string maxLength: 1000 principalType: description: Principal type of role. type: string format: enum enum: - user - service permissionSets: description: List of permission sets. type: array items: type: string uniqueItems: true minItems: 1 example: name: Endpoint Admin description: Admin role principalType: user permissionSets: - central_admin - endpoint_product_admin responses: '201': description: Role created. content: application/json: schema: type: object description: Tenant role. required: - id - name - type - principalType - permissionSets properties: id: description: Role UUID. type: string format: uuid name: description: Role name. type: string description: description: Role Description. type: string type: description: Role type. type: string format: enum enum: - predefined - custom principalType: description: Principal type of role. type: string format: enum enum: - user - service permissionSets: description: List of permission sets. type: array items: type: string uniqueItems: true minItems: 1 createdAt: description: Date and time tenant role was created. type: string format: datetime updatedAt: description: Date and time tenant role was last updated. type: string format: datetime '409': description: Role name already in use or is a pre-defined role name. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/roles/{roleId}': get: x-soph-permissions: 'role:read' summary: Get role by ID description: Get tenant role by ID. operationId: getTenantRoleById tags: - Tenant role management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: roleId description: Role ID. required: true schema: type: string format: uuid responses: '200': description: Details of requested role. content: application/json: schema: type: object description: Tenant role. required: - id - name - type - principalType - permissionSets properties: id: description: Role UUID. type: string format: uuid name: description: Role name. type: string description: description: Role Description. type: string type: description: Role type. type: string format: enum enum: - predefined - custom principalType: description: Principal type of role. type: string format: enum enum: - user - service permissionSets: description: List of permission sets. type: array items: type: string uniqueItems: true minItems: 1 createdAt: description: Date and time tenant role was created. type: string format: datetime updatedAt: description: Date and time tenant role was last updated. type: string format: datetime '404': description: Can't find role. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri delete: x-soph-permissions: 'role:write' summary: Delete role by ID description: Delete a tenant role by ID. operationId: deleteTenantRoleById tags: - Tenant role management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: roleId description: Role ID. required: true schema: type: string format: uuid responses: '200': description: Role deleted. content: application/json: schema: type: object description: Response to a previous request to delete an item. required: - deleted properties: deleted: type: boolean '409': description: You can't delete a role assigned to an admin. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri patch: x-soph-permissions: 'role:update' summary: Patch role description: Patch an existing tenant role. operationId: patchTenantRole tags: - Tenant role management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: path name: roleId description: Role ID. required: true schema: type: string format: uuid requestBody: description: Json Merge Patch request. required: true content: application/json: schema: type: object description: Patch request for a role. properties: name: description: Role name. type: string maxLength: 100 description: description: Role description. type: string maxLength: 1000 permissionSets: description: Permission sets to be updated. oneOf: - allOf: - type: object description: Base class for permission sets. - type: object description: Set of permissions to operate on. properties: permissionSets: type: array items: type: string uniqueItems: true description: Set of permissions to operate on. - allOf: - type: object description: Base class for permission sets. - type: object description: >- Update permission set by adding or removing permissions. properties: add: type: array items: type: string uniqueItems: true description: Permissions to add. remove: type: array items: type: string uniqueItems: true description: Permissions to remove. example: name: Endpoint Admin description: Admin role permissionSets: - central_admin - endpoint_product_admin responses: '200': description: Updated role. content: application/json: schema: type: object description: Tenant role. required: - id - name - type - principalType - permissionSets properties: id: description: Role UUID. type: string format: uuid name: description: Role name. type: string description: description: Role Description. type: string type: description: Role type. type: string format: enum enum: - predefined - custom principalType: description: Principal type of role. type: string format: enum enum: - user - service permissionSets: description: List of permission sets. type: array items: type: string uniqueItems: true minItems: 1 createdAt: description: Date and time tenant role was created. type: string format: datetime updatedAt: description: Date and time tenant role was last updated. type: string format: datetime '404': description: Role not found with given ID. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '409': description: Role name already in use or is a pre-defined role name. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /roles/permission-sets: get: x-soph-permissions: 'permission-set:list' summary: Get permission sets description: Get permission set details. operationId: getRolePermissionSet tags: - Tenant role management parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string - in: query name: type description: Permission set type. required: false schema: description: Type of permission set. type: string format: enum enum: - base - product - setting - in: query name: product description: Filter permission sets associated with given product name. required: false schema: description: Products list. type: string format: enum enum: - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - optix - ztna - in: query name: access description: Access level of permission set. required: false schema: description: Access level of a permission set. type: string format: enum enum: - admin - helpdesk - readOnly - in: query name: allowedInCustomRole description: Filter permissions sets allowed in custom roles. required: false schema: type: boolean - in: query name: principalType description: Principal type of role. required: false schema: description: Principal type of role. type: string format: enum enum: - user - service responses: '200': description: List of permission sets. content: application/json: schema: type: object description: List of permission sets. required: - items properties: items: type: array description: List of permission sets. items: type: object description: A permission set. required: - id - name - type - principalTypes - allowedInCustomRoles properties: id: description: Permission set identifier. type: string name: description: Permission set name. type: string description: description: Permission set description. type: string type: description: Type of permission set. type: string format: enum enum: - base - product - setting access: description: Access level of a permission set. type: string format: enum enum: - admin - helpdesk - readOnly principalTypes: description: Principal types for which permission set is allowed. type: array items: description: Principal type of role. type: string format: enum enum: - user - service products: description: >- List of products associated to a permission set of type product. type: array items: description: Products list. type: string format: enum enum: - endpoint - server - mobile - encryption - emailGateway - webGateway - phishThreat - wireless - firewall - optix - ztna uniqueItems: true allowedInCustomRoles: description: >- Signifies if permission set is allowed in a custom role. type: boolean '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT