openapi: 3.0.0 info: description: >- This is the OAS 3.0 specification for the Organization API in Sophos Central. version: 1.10.0 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' title: Organization API tags: - name: Organization Admins description: Manage Organization admins. - name: Organization role management description: Central role management API for organizations. - name: OrganizationTenants description: List tenants or view tenant details. servers: - url: 'https://api.central.sophos.com/organization/v1' description: Global service in the production environment. security: - bearerAuth: [] paths: /admins: get: summary: List all admins description: List all organization admins. x-soph-permissions: 'account_management:read' operationId: getOrganizationAdmins tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - 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: 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 - in: query name: email description: Search by email. required: false schema: type: string - in: query name: roleId description: Search by role ID. required: false schema: type: string format: uuid - in: query name: withAccessToTenant description: Search for admins that have access to the given tenant. required: false schema: type: string format: uuid responses: '200': description: Paged array of organization admins. content: application/json: schema: type: object description: Page of organization administrators. required: - items - pages properties: items: description: Organization administrators. type: array items: type: object description: Organization administrator. allOf: - type: object description: Administrator. required: - id - username - profile - active - primary - roleAssignments properties: id: description: Administrator ID. type: string format: uuid username: description: Administrator username (email). type: string format: email profile: type: object description: >- Profile information for organization administrator. required: - firstName - lastName - name properties: name: description: Full name. type: string firstName: description: First name. type: string lastName: description: Last name. type: string phone: description: Phone number. type: string mobile: description: Mobile phone number. type: string fax: description: Fax number. type: string active: description: Whether the administrator is active. type: boolean primary: description: >- Whether this is the primary administrator for the account. type: boolean default: false roleAssignments: description: Administrator's role assignments. type: array items: type: object description: Role assignment. required: - id - roleId - scope properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role ID. type: string format: uuid roleName: description: Role name. type: string scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid name: description: >- Tenant name. Optional or not present when `type` is `allManagedTenants` or `self`. type: string 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: 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 post: summary: Create a new admin description: Create a new organization administrator. x-soph-permissions: 'account_management:write' operationId: createOrganizationAdmin tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid requestBody: description: New admin creation request. required: true content: application/json: schema: type: object description: New organization administrator. required: - username - profile properties: username: description: Administrator username (email). type: string format: email profile: type: object description: Profile information for organization administrator. required: - firstName - lastName - name properties: name: description: Full name. type: string firstName: description: First name. type: string lastName: description: Last name. type: string phone: description: Phone number. type: string mobile: description: Mobile phone number. type: string fax: description: Fax number. type: string roleAssignments: description: Role assignments. type: array items: type: object description: New role assignment request. required: - roleId - scope properties: roleId: description: Role ID. type: string format: uuid scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid examples: NewOrganizationAdminRequest: value: username: john.smith@example.com profile: name: John J. Smith firstName: John lastName: Smith roleAssignments: - roleId: 70617274-6e65-7273-7570-657261646d69 scope: type: self responses: '201': description: Requested admin created. content: application/json: schema: type: object description: Organization administrator. allOf: - type: object description: Administrator. required: - id - username - profile - active - primary - roleAssignments properties: id: description: Administrator ID. type: string format: uuid username: description: Administrator username (email). type: string format: email profile: type: object description: Profile information for organization administrator. required: - firstName - lastName - name properties: name: description: Full name. type: string firstName: description: First name. type: string lastName: description: Last name. type: string phone: description: Phone number. type: string mobile: description: Mobile phone number. type: string fax: description: Fax number. type: string active: description: Whether the administrator is active. type: boolean primary: description: >- Whether this is the primary administrator for the account. type: boolean default: false roleAssignments: description: Administrator's role assignments. type: array items: type: object description: Role assignment. required: - id - roleId - scope properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role ID. type: string format: uuid roleName: description: Role name. type: string scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid name: description: >- Tenant name. Optional or not present when `type` is `allManagedTenants` or `self`. type: string '400': description: Bad 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: Email address already in use. 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: 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 '/admins/{adminId}': get: summary: Get an admin by ID description: Get organization administrator details by ID. x-soph-permissions: 'account_management:read' operationId: getOrganizationAdminById tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: adminId in: path description: Admin ID. required: true schema: type: string responses: '200': description: Details of the requested organization administrator. content: application/json: schema: type: object description: Organization administrator. allOf: - type: object description: Administrator. required: - id - username - profile - active - primary - roleAssignments properties: id: description: Administrator ID. type: string format: uuid username: description: Administrator username (email). type: string format: email profile: type: object description: Profile information for organization administrator. required: - firstName - lastName - name properties: name: description: Full name. type: string firstName: description: First name. type: string lastName: description: Last name. type: string phone: description: Phone number. type: string mobile: description: Mobile phone number. type: string fax: description: Fax number. type: string active: description: Whether the administrator is active. type: boolean primary: description: >- Whether this is the primary administrator for the account. type: boolean default: false roleAssignments: description: Administrator's role assignments. type: array items: type: object description: Role assignment. required: - id - roleId - scope properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role ID. type: string format: uuid roleName: description: Role name. type: string scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid name: description: >- Tenant name. Optional or not present when `type` is `allManagedTenants` or `self`. type: string '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 '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 delete: x-soph-permissions: 'account_management:write' summary: Remove an admin description: Remove an admin by ID. operationId: deleteOrganizationAdminById tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: adminId in: path description: Admin ID. required: true schema: type: string 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: description: Whether it has been truly 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: summary: List all roles description: Get the list of role assignments for given admin. x-soph-permissions: 'account_management:read' operationId: getAdminRoleAssignments tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: adminId in: path description: Admin ID. required: true schema: type: string responses: '200': description: A list of role assignments for an admin. content: application/json: schema: type: object description: List of role assignments. required: - items properties: items: description: Role assignments. type: array items: type: object description: Role assignment. required: - id - roleId - scope properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role ID. type: string format: uuid roleName: description: Role name. type: string scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid name: description: >- Tenant name. Optional or not present when `type` is `allManagedTenants` or `self`. type: string uniqueItems: 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 '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 post: summary: Assign a role description: Assign a role to a organization administrator. x-soph-permissions: 'account_management:write' operationId: createAdminRoleAssignment tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: adminId in: path description: Admin ID. required: true schema: type: string requestBody: description: New role assignment request. required: true content: application/json: schema: type: object description: New role assignment request. required: - roleId - scope properties: roleId: description: Role ID. type: string format: uuid scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid examples: NewRoleAssignmentRequest: value: roleId: 2b8f2624-b054-45e0-923e-6527d9054342 scope: type: self responses: '201': description: Requested assignment created. content: application/json: schema: type: object description: Role assignment. required: - id - roleId - scope properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role ID. type: string format: uuid roleName: description: Role name. type: string scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid name: description: >- Tenant name. Optional or not present when `type` is `allManagedTenants` or `self`. type: string '400': description: Bad 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 '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 '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 '/admins/{adminId}/role-assignments/{assignmentId}': get: summary: Get role by ID description: Get organization administrator role assignment by ID. x-soph-permissions: 'account_management:read' operationId: getAdminRoleAssignmentById tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: adminId in: path description: Admin ID. required: true schema: type: string - name: assignmentId in: path description: Role assignment ID. required: true schema: type: string format: uuid responses: '200': description: Details of role assignment. content: application/json: schema: type: object description: Role assignment. required: - id - roleId - scope properties: id: description: Role assignment ID. type: string format: uuid roleId: description: Role ID. type: string format: uuid roleName: description: Role name. type: string scope: type: object description: Role assignment scope. required: - type properties: type: type: string description: Role assignment scope type. enum: - tenant - allManagedTenants - self - tenantGroup id: description: >- Tenant ID. Optional or not present when `type` is `allManagedTenants` or `self`. type: string format: uuid name: description: >- Tenant name. Optional or not present when `type` is `allManagedTenants` or `self`. type: string '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 '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 delete: summary: Remove a role description: Remove role assignment from an admin. x-soph-permissions: 'account_management:write' operationId: removeAdminRoleAssignmentById tags: - Organization Admins parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: adminId in: path description: Admin ID. required: true schema: type: string - name: assignmentId in: path description: Role assignment ID. required: true schema: type: string format: uuid responses: '200': description: Role assignment removed. content: application/json: schema: type: object description: Response to the request to delete a role assignment. additionalProperties: false '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 /tenants: get: tags: - OrganizationTenants summary: Enumerate tenants description: Get all the tenants in the specified organization. x-soph-permissions: - 'account_management:read' - 'organization:listMembers' operationId: listTenantsInOrganization parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: ids in: query description: Tenant IDs. required: false schema: type: array items: type: string format: uuid uniqueItems: true maxItems: 50 - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - 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. - name: managed description: >- Match tenants by whether they have enabled management by this organization. in: query required: false schema: type: boolean default: false responses: '200': description: Page of tenants. content: application/json: schema: type: object description: Page of tenants. required: - items - pages properties: items: type: array description: List of tenants. items: type: object description: Tenant. required: - id - name - dataGeography - dataRegion - billingType - organization - apiHost properties: id: type: string description: Tenant ID. format: uuid showAs: type: string description: Tenant display name. name: type: string description: Name set when the tenant was created. dataGeography: type: string description: >- Geographical location where the tenant data is stored. enum: - US - IE - DE - CA - AU - JP - IN - BR - AE dataRegion: type: string description: The data region where tenant data is stored. enum: - eu01 - eu02 - us01 - us02 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 billingType: type: string description: Billing type. enum: - term - trial - usage partner: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. organization: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. apiHost: type: string description: API host. format: uri managed: type: boolean description: >- Indicates if tenant has enabled management by this organization. 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: 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 '/tenants/{tenantId}': get: tags: - OrganizationTenants summary: Get tenant details description: Get a tenant by ID. x-soph-permissions: - 'account_management:read' - 'organization:listMembers' operationId: getTenantById parameters: - name: X-Organization-ID in: header description: Organization ID. required: true schema: type: string format: uuid - name: tenantId in: path description: Tenant ID. required: true schema: type: string format: uuid responses: '200': description: Existing tenant. content: application/json: schema: type: object description: Tenant. required: - id - name - dataGeography - dataRegion - billingType - organization - apiHost properties: id: type: string description: Tenant ID. format: uuid showAs: type: string description: Tenant display name. name: type: string description: Name set when the tenant was created. dataGeography: type: string description: Geographical location where the tenant data is stored. enum: - US - IE - DE - CA - AU - JP - IN - BR - AE dataRegion: type: string description: The data region where tenant data is stored. enum: - eu01 - eu02 - us01 - us02 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 billingType: type: string description: Billing type. enum: - term - trial - usage partner: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. organization: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. apiHost: type: string description: API host. format: uri managed: type: boolean description: >- Indicates if tenant has enabled management by this organization. '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 /roles: get: x-soph-permissions: 'organization-role:list' summary: List all roles description: List all organization roles. operationId: listOrganizationRoles tags: - Organization role management parameters: - name: X-Organization-ID in: header description: Organization 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 roles used in an organization. content: application/json: schema: type: object description: List of roles. required: - items properties: items: type: array description: List of roles. items: type: object description: Organization 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 the organization role was created. type: string format: datetime updatedAt: description: >- Date and time the organization 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: 'organization-role:create' summary: Create new role description: Create a new organization role. operationId: createOrganizationRole tags: - Organization role management parameters: - name: X-Organization-ID in: header description: Organization 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 organization 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 examples: NewRoleRequest: value: name: Organization custom role description: Organization custom role principalType: user permissionSets: - enterprise_admin - endpoint_product_admin responses: '201': description: Requested role created. content: application/json: schema: type: object description: Organization 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 the organization role was created. type: string format: datetime updatedAt: description: Date and time the organization 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: 'organization-role:read' summary: Get role by ID description: Get organization role by ID. operationId: getOrganizationRoleById tags: - Organization role management parameters: - name: X-Organization-ID in: header description: Organization 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: Organization 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 the organization role was created. type: string format: datetime updatedAt: description: Date and time the organization role was last updated. type: string format: datetime '404': description: Resource not found. 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: 'organization-role:delete' summary: Delete role by ID description: Delete a organization role by ID. operationId: deleteOrganizationRoleById tags: - Organization role management parameters: - name: X-Organization-ID in: header description: Organization 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: Requested role deleted. content: application/json: schema: type: object description: Delete Response. 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: 'organization-role:update' summary: Patch role description: Patch an existing organization role. operationId: patchOrganizationRole tags: - Organization role management parameters: - name: X-Organization-ID in: header description: Organization 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. examples: RolePatchRequest: value: name: Organization custom role description: Organization custom role permissionSets: - enterprise_admin - endpoint_product_admin responses: '200': description: Updated role. content: application/json: schema: type: object description: Organization 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 the organization role was created. type: string format: datetime updatedAt: description: Date and time the organization role was last updated. type: string format: datetime '404': description: No role 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: 'organization-permission-set:list' summary: Get permission sets description: Get permission set details. operationId: getRolePermissionSet tags: - Organization role management parameters: - name: X-Organization-ID in: header description: Organization 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: Type of permission set. 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: 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 with 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