openapi: 3.1.0
info:
  title: Access Management API
  version: v3
servers:
  - url: https://api-ext-sboxmeta.partners.spotnana.com
    description: Sandbox URL
security:
  - Bearer: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ApplicableScope:
      type: object
      title: ApplicableScope
      description: >-
        An applicable scope indicating the predicate type and its permitted
        values.
      required:
        - predicateType
      properties:
        predicateType:
          $ref: '#/components/schemas/ScopePredicateType'
        allowedValues:
          type: array
          description: >-
            Allowed values for this predicate type. Present for predicate types
            that have enumerable values (e.g. STEALTH_TYPE).
          items:
            $ref: '#/components/schemas/ScopePredicateValue'
    AudiencePredicate:
      type: object
      title: AudiencePredicate
      description: Predicate granting access to a subset of platform.
      discriminator:
        propertyName: type
        mapping:
          PLATFORM: '#/components/schemas/PlatformPredicate'
          BOOKING_TMC: '#/components/schemas/BookingTmcPredicate'
          CONTRACTING_TMC: '#/components/schemas/ContractingTmcPredicate'
          COMPANY: '#/components/schemas/CompanyPredicate'
          LEGAL_ENTITY: '#/components/schemas/LegalEntityPredicate'
          PROFILE: '#/components/schemas/ProfilePredicate'
          STEALTH_TYPE: '#/components/schemas/StealthTypePredicate'
          TRIP_TEMPLATE: '#/components/schemas/TripTemplatePredicate'
      oneOf:
        - $ref: '#/components/schemas/PlatformPredicate'
        - $ref: '#/components/schemas/BookingTmcPredicate'
        - $ref: '#/components/schemas/ContractingTmcPredicate'
        - $ref: '#/components/schemas/CompanyPredicate'
        - $ref: '#/components/schemas/LegalEntityPredicate'
        - $ref: '#/components/schemas/ProfilePredicate'
        - $ref: '#/components/schemas/StealthTypePredicate'
        - $ref: '#/components/schemas/TripTemplatePredicate'
    BookingTmcPredicate:
      title: BookingTmcPredicate
      description: Compare the booking tmc of the traveler with the values.
      required:
        - type
        - comparator
        - values
      properties:
        type:
          type: string
          default: BOOKING_TMC
        comparator:
          $ref: '#/components/schemas/ScopeEntitiesComparator'
        values:
          type: array
          description: List of UUID values to compare.
          minItems: 1
          items:
            type: string
            format: uuid
          example:
            - 1234a66b-7493-4f41-908c-58ba81093947
        valuesWithLabel:
          type: array
          description: Values with labels
          minItems: 1
          items:
            $ref: '#/components/schemas/Reference'
    CompanyPredicate:
      title: CompanyPredicate
      description: Compare the traveler company with the values.
      required:
        - type
        - comparator
        - values
      properties:
        type:
          type: string
          default: COMPANY
        comparator:
          $ref: '#/components/schemas/ScopeEntitiesComparator'
        values:
          type: array
          description: List of UUID values to compare.
          minItems: 1
          items:
            type: string
            format: uuid
          example:
            - 1234a66b-7493-4f41-908c-58ba81093947
        valuesWithLabel:
          type: array
          description: Values with labels
          minItems: 1
          items:
            $ref: '#/components/schemas/Reference'
    ContractingTmcPredicate:
      title: ContractingTmcPredicate
      description: Compare the contracting TMC of the traveler with the values.
      required:
        - type
        - comparator
        - values
      properties:
        type:
          type: string
          default: CONTRACTING_TMC
        comparator:
          $ref: '#/components/schemas/ScopeEntitiesComparator'
        values:
          type: array
          description: List of UUID values to compare.
          minItems: 1
          items:
            type: string
            format: uuid
          example:
            - 1234a66b-7493-4f41-908c-58ba81093947
        valuesWithLabel:
          type: array
          description: Values with labels
          minItems: 1
          items:
            $ref: '#/components/schemas/Reference'
    CreateRoleRequest:
      type: object
      title: CreateRoleRequest
      description: Role create request.
      required:
        - name
        - description
        - isPlatformRole
        - permissions
      properties:
        name:
          type: string
          description: Name of the role.
          example: User Admin
        description:
          type: string
          description: A short description of the role mentioning what can it do.
          example: Manage users for the company.
        isPlatformRole:
          type: boolean
          default: false
          description: Whether role is platform provided.
          example: false
        companyId:
          type: string
          format: uuid
          description: Company ID which owns the role.
          example: 1aeef911-44cf-49bb-83c7-e06b0d4e7ac2
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/PermissionWithActions'
          description: Permissions granted to the role.
    DateTimeOffset:
      title: DateTimeOffset
      description: ISO8601 UTC Date Time
      type: object
      required:
        - iso8601
      properties:
        iso8601:
          type: string
          pattern: >-
            ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-4]):([0-5][0-9])(:([0-5][0-9]))?(Z|([+-](0[0-9]|1[0-4]):([0-5][0-9])))$
          example: 2017-07-21T17:32Z
    EntityId:
      type: object
      description: Identifier of an object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          example: b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3
    ErrorParameter:
      type: object
      title: ErrorParameter
      description: Error parameter
      properties:
        name:
          type: string
          description: Parameter name
        value:
          type: string
          description: Parameter value
    ErrorResponse:
      type: object
      properties:
        debugIdentifier:
          type: string
          description: Link to debug the error internally.
        errorMessages:
          type: array
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: Error code to identify the specific errors.
              message:
                type: string
                description: Message containing details of error.
              errorParameters:
                type: array
                description: Error message parameters.
                items:
                  $ref: '#/components/schemas/ErrorParameter'
              errorDetail:
                type: string
                description: More details about the error.
    GetApplicableScopesRequest:
      type: object
      title: GetApplicableScopesRequest
      description: Request to get applicable scopes for selected roles.
      properties:
        roleIds:
          type: array
          description: List of selected role identifiers.
          items:
            type: string
            format: uuid
          example:
            - 1aeef911-44cf-49bb-83c7-e06b0d4e7ac2
        selectedAudience:
          $ref: '#/components/schemas/ScopeAudience'
    GetApplicableScopesResponse:
      type: object
      title: GetApplicableScopesResponse
      description: Response containing applicable scopes for the selected roles.
      required:
        - applicableScopes
      properties:
        applicableScopes:
          type: array
          description: >-
            List of applicable scopes with their predicate types and permitted
            values.
          items:
            $ref: '#/components/schemas/ApplicableScope'
    GetEntityPermissionsRequest:
      type: object
      title: GetEntityPermissionsRequest
      description: Request to get permissions on an entity.
      required:
        - entityId
        - entityType
      properties:
        entityId:
          type: string
          description: Unique identifier of the entity.
          example: 4974a66b-7493-4f41-908c-58ba81093947
        entityType:
          $ref: '#/components/schemas/ScopeEntityType'
    GetEntityPermissionsResponse:
      type: object
      title: GetEntityPermissionsResponse
      description: Response containing permissions on an entity.
      required:
        - permissions
      properties:
        permissions:
          type: array
          description: List of permissions user has on the entity.
          items:
            $ref: '#/components/schemas/PermissionWithActions'
    GetRbacInfoResponse:
      type: object
      title: GetRbacInfoResponse
      description: Response containing RBAC info for a user.
      required:
        - hasOthersTripAccess
        - permissions
      properties:
        hasOthersTripAccess:
          type: boolean
          description: Flag indicating whether user has access to trips of other travelers.
          example: true
        permissions:
          type: array
          description: List of permissions with their associated actions for the user.
          items:
            $ref: '#/components/schemas/PermissionWithActions'
    LegalEntityPredicate:
      title: LegalEntityPredicate
      description: Compare the traveler legal entity with the values.
      required:
        - type
        - comparator
        - values
      properties:
        type:
          type: string
          default: LEGAL_ENTITY
        comparator:
          $ref: '#/components/schemas/ScopeEntitiesComparator'
        values:
          type: array
          description: List of UUID values to compare.
          minItems: 1
          items:
            type: string
            format: uuid
          example:
            - 1234a66b-7493-4f41-908c-58ba81093947
        valuesWithLabel:
          type: array
          description: Values with labels
          minItems: 1
          items:
            $ref: '#/components/schemas/Reference'
    ListPermissionsResponse:
      type: object
      title: ListPermissionsResponse
      description: Response containing list of available permissions.
      required:
        - permissions
      properties:
        permissions:
          type: array
          description: List of available permissions.
          items:
            $ref: '#/components/schemas/Permission'
    ListRoleFilter:
      type: object
      title: ListRoleFilter
      description: Filter parameters for roles.
      properties:
        roleIds:
          type: array
          items:
            type: string
            format: uuid
          description: List of role ids.
        roleProvidedBy:
          type: array
          items:
            $ref: '#/components/schemas/RoleProvidedBy'
          description: Filter by role providers.
    ListRolesRequest:
      type: object
      title: ListRolesRequest
      description: List roles request.
      required:
        - pagination
      properties:
        searchText:
          type: string
          description: Query text to search roles. The match would be case-insensitive.
          example: Admin
        pagination:
          description: Pagination information for request.
          $ref: '#/components/schemas/OffsetBasedPaginationRequestParams'
        sortParams:
          description: Sorting related parameters.
          $ref: '#/components/schemas/RoleSortParams'
        filters:
          type: array
          description: List of filters. Roles matching with any filter would be returned.
          items:
            $ref: '#/components/schemas/ListRoleFilter'
    ListRolesResponse:
      type: object
      title: ListRolesResponse
      description: List roles response.
      required:
        - roles
        - pagination
      properties:
        roles:
          type: array
          description: Roles matching with the request.
          items:
            $ref: '#/components/schemas/RoleV3'
        pagination:
          $ref: '#/components/schemas/OffsetBasedPaginationResponseParams'
          description: Pagination information for response.
    ListUserGroupFilter:
      type: object
      title: ListUserGroupFilter
      description: Filter parameters for user groups.
      properties:
        userGroupIds:
          type: array
          items:
            type: string
            format: uuid
          description: List of user group ids.
    ListUserGroupMemberFilter:
      type: object
      title: ListUserGroupMemberFilter
      description: Filter parameters for user group members.
      properties:
        addedAfter:
          description: Filter by users added after this date (inclusive).
          $ref: '#/components/schemas/DateTimeOffset'
        addedBefore:
          description: Filter by users added before this date (exclusive).
          $ref: '#/components/schemas/DateTimeOffset'
        userIds:
          type: array
          items:
            type: string
            format: uuid
          description: Filter by specific user IDs.
          example:
            - 1234a66b-7493-4f41-908c-58ba81093947
    ListUserGroupMembersRequest:
      type: object
      title: ListUserGroupMembersRequest
      description: List user group members request.
      required:
        - pagination
      properties:
        pagination:
          description: Pagination information for request.
          $ref: '#/components/schemas/OffsetBasedPaginationRequestParams'
        sortParams:
          description: Sorting related parameters.
          $ref: '#/components/schemas/UserGroupMemberSortParams'
        filters:
          type: array
          description: List of filters. Members matching with any filter would be returned.
          items:
            $ref: '#/components/schemas/ListUserGroupMemberFilter'
    ListUserGroupMembersResponse:
      type: object
      title: ListUserGroupMembersResponse
      description: List user group members response.
      required:
        - members
        - pagination
      properties:
        members:
          type: array
          description: List of user group members with their details.
          items:
            $ref: '#/components/schemas/UserGroupMember'
        pagination:
          $ref: '#/components/schemas/OffsetBasedPaginationResponseParams'
          description: Pagination information for response.
    ListUserGroupRolesRequest:
      type: object
      title: ListUserGroupRolesRequest
      description: List user group roles request.
      required:
        - pagination
      properties:
        searchText:
          type: string
          description: Query text to search roles. The match would be case-insensitive.
          example: Admin
        pagination:
          description: Pagination information for request.
          $ref: '#/components/schemas/OffsetBasedPaginationRequestParams'
        sortParams:
          description: Sorting related parameters.
          $ref: '#/components/schemas/RoleSortParams'
        filters:
          type: array
          description: List of filters. Roles matching with any filter would be returned.
          items:
            $ref: '#/components/schemas/ListRoleFilter'
    ListUserGroupRolesResponse:
      type: object
      title: ListUserGroupRolesResponse
      description: List user group roles response.
      required:
        - roles
        - pagination
      properties:
        roles:
          type: array
          description: Roles assigned to the group matching with the request.
          items:
            $ref: '#/components/schemas/RoleWithScope'
        pagination:
          $ref: '#/components/schemas/OffsetBasedPaginationResponseParams'
          description: Pagination information for response.
    ListUserGroupsRequest:
      type: object
      title: ListUserGroupsRequest
      description: List user groups request.
      required:
        - pagination
      properties:
        searchText:
          type: string
          description: >-
            Query text to search user groups. The match would be
            case-insensitive.
          example: Company Admins
        pagination:
          description: Pagination information for request.
          $ref: '#/components/schemas/OffsetBasedPaginationRequestParams'
        sortParams:
          description: Sorting related parameters.
          $ref: '#/components/schemas/UserGroupSortParams'
        filters:
          type: array
          description: >-
            List of filters. User groups matching with any filter would be
            returned.
          items:
            $ref: '#/components/schemas/ListUserGroupFilter'
    ListUserGroupsResponse:
      type: object
      title: ListUserGroupsResponse
      description: List user groups response.
      required:
        - userGroups
        - pagination
      properties:
        userGroups:
          type: array
          description: User groups matching with the request.
          items:
            $ref: '#/components/schemas/RoleUserGroup'
        pagination:
          $ref: '#/components/schemas/OffsetBasedPaginationResponseParams'
          description: Pagination information for response.
    ListUserRolesRequest:
      type: object
      title: ListUserRolesRequest
      description: List user roles request.
      required:
        - pagination
      properties:
        searchText:
          type: string
          description: Query text to search roles. The match would be case-insensitive.
          example: Admin
        pagination:
          description: Pagination information for request.
          $ref: '#/components/schemas/OffsetBasedPaginationRequestParams'
        sortParams:
          description: Sorting related parameters.
          $ref: '#/components/schemas/RoleSortParams'
        filters:
          type: array
          description: List of filters. Roles matching with any filter would be returned.
          items:
            $ref: '#/components/schemas/ListRoleFilter'
    ListUserRolesResponse:
      type: object
      title: ListUserRolesResponse
      description: List user roles response.
      required:
        - roles
        - pagination
      properties:
        roles:
          type: array
          description: Roles assigned to the user matching with the request.
          items:
            $ref: '#/components/schemas/RoleWithScope'
        pagination:
          $ref: '#/components/schemas/OffsetBasedPaginationResponseParams'
          description: Pagination information for response.
    NonUuidReference:
      type: object
      title: NonUuidReference
      description: Reference object containing id and name of the entity.
      required:
        - id
      properties:
        id:
          type: string
          example: '1234567'
        name:
          type: string
          example: Name
    OffsetBasedPaginationRequestParams:
      type: object
      title: OffsetBasedPaginationRequestParams
      description: Pagination parameters for requests.
      properties:
        offset:
          type: integer
          format: int32
          description: >-
            The starting index in the list from which results are returned. The
            value must be greater than or equal to 0.
          default: 0
          minimum: 0
        limit:
          type: integer
          format: int32
          description: Maximum number of results to be fetched.
          minimum: 1
          default: 100
    OffsetBasedPaginationResponseParams:
      type: object
      title: PaginationResponseParams
      description: Pagination parameters for response.
      required:
        - totalNumResults
      properties:
        totalNumResults:
          type: integer
          format: int32
          description: Total number of results.
    Permission:
      type: object
      title: Permission
      description: Permission definition.
      required:
        - name
        - description
      properties:
        name:
          $ref: '#/components/schemas/PermissionName'
        description:
          type: string
          description: Description of the permission.
          example: Manage company settings and configurations.
        parentName:
          $ref: '#/components/schemas/PermissionName'
    PermissionAction:
      type: string
      title: PermissionAction
      description: Actions which can be performed for a given permission.
      enum:
        - ALL
        - CREATE
        - READ
        - WRITE
        - DELETE
        - PURGE
      example: READ
    PermissionName:
      type: string
      title: PermissionName
      description: Permission
      enum:
        - PLATFORM_MANAGEMENT
        - TMC_MANAGEMENT
        - COMPANY_MANAGEMENT
        - USER_MANAGEMENT
        - USER_PROFILE
        - EVENT_MANAGEMENT
        - REPORT_MANAGEMENT
        - ACCESS_MANAGEMENT
        - TRIP_MANAGEMENT
        - AGENT
        - DEVELOPER_PLATFORM_MANAGEMENT
        - THIRD_PARTY_NOTIFICATION_MANAGEMENT
      example: COMPANY_MANAGEMENT
    PermissionWithActions:
      type: object
      title: PermissionWithActions
      description: Permission with actions
      required:
        - permission
        - actions
      properties:
        permission:
          $ref: '#/components/schemas/PermissionName'
          example: USER_MANAGEMENT
        actions:
          type: array
          items:
            $ref: '#/components/schemas/PermissionAction'
          description: Actions allowed on the permission like read/write/delete.
          example:
            - READ
            - WRITE
    PlatformPredicate:
      type: object
      title: PlatformPredicate
      description: Predicate granting access to the entire platform.
      required:
        - type
        - value
      properties:
        type:
          type: string
          default: PLATFORM
        value:
          type: boolean
          default: false
          example: false
    ProfilePredicate:
      title: ProfilePredicate
      description: Compare the traveler's user id with the values.
      required:
        - type
        - comparator
        - values
      properties:
        type:
          type: string
          default: PROFILE
        comparator:
          $ref: '#/components/schemas/ScopeEntitiesComparator'
        values:
          type: array
          description: List of UUID values to compare.
          minItems: 1
          items:
            type: string
            format: uuid
          example:
            - 1234a66b-7493-4f41-908c-58ba81093947
        valuesWithLabel:
          type: array
          description: Values with labels
          minItems: 1
          items:
            $ref: '#/components/schemas/Reference'
    Reference:
      type: object
      title: Reference object containing uuid and name of the entity.
      description: Reference of an entity
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          example: b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3
        name:
          type: string
          example: Name
    RoleProvidedBy:
      type: string
      title: RoleProvidedBy
      description: The role provider ie platform or company.
      enum:
        - PLATFORM
        - COMPANY
    RoleRefWithScope:
      type: object
      title: RoleRefWithScope
      description: Role reference with scope information.
      required:
        - roleId
        - scope
      properties:
        roleId:
          type: string
          format: uuid
          description: Role identifier.
          example: 1aeef911-44cf-49bb-83c7-e06b0d4e7ac2
        scope:
          $ref: '#/components/schemas/Scope'
    RoleSortField:
      type: string
      title: RoleSortField
      description: The field name to sort roles.
      enum:
        - NAME
      default: NAME
    RoleSortParams:
      type: object
      title: RoleSortParams
      description: Sorting related parameters to return sorted list of roles.
      required:
        - sortBy
        - sortOrder
      properties:
        sortBy:
          $ref: '#/components/schemas/RoleSortField'
        sortOrder:
          $ref: '#/components/schemas/SortOrder'
    RoleUserGroup:
      type: object
      title: RoleUserGroup
      description: User group
      required:
        - id
        - name
        - description
        - companyId
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
      properties:
        id:
          type: string
          format: uuid
          description: User group identifier.
          example: 4974a66b-7493-4f41-908c-58ba81093947
        name:
          type: string
          description: Name of the user group.
          example: Company Admins
        description:
          type: string
          description: A description of the user group.
          example: Group for managing the company settings.
        companyId:
          type: string
          format: uuid
          description: Company ID of the user group.
          example: 1234a66b-7493-4f41-908c-58ba81093653
        createdAt:
          description: Date and time when the user group was created.
          $ref: '#/components/schemas/DateTimeOffset'
        updatedAt:
          description: Date and time when the user group was last updated.
          $ref: '#/components/schemas/DateTimeOffset'
        createdBy:
          description: User who created the user group.
          $ref: '#/components/schemas/Reference'
        updatedBy:
          description: User who last updated the user group.
          $ref: '#/components/schemas/Reference'
        isUnmodifiable:
          description: >
            Whether the group is not modifiable. This would be set true only for
            platform created groups.

            Only group name, description and assigned roles & scopes can not be
            modified but members 

            can still be updated.
          type: boolean
          default: false
    RoleV3:
      type: object
      title: RoleV3
      description: Role information.
      required:
        - id
        - name
        - description
        - isPlatformRole
        - permissions
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
      properties:
        id:
          type: string
          format: uuid
          description: Role identifier.
        name:
          type: string
          description: Name of the role.
          example: User Admin
        description:
          type: string
          description: A short description of the role mentioning what can it do.
          example: Manage users for the company.
        isPlatformRole:
          type: boolean
          default: false
          description: Whether role is platform provided.
          example: false
        companyId:
          type: string
          format: uuid
          description: Company ID which owns the role.
          example: 1aeef911-44cf-49bb-83c7-e06b0d4e7ac2
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/PermissionWithActions'
          description: Permissions granted to the role.
        createdAt:
          description: Date and time when the role was created.
          $ref: '#/components/schemas/DateTimeOffset'
        updatedAt:
          description: Date and time when the role was last updated.
          $ref: '#/components/schemas/DateTimeOffset'
        createdBy:
          description: User who created the role.
          $ref: '#/components/schemas/Reference'
        updatedBy:
          description: User who last updated the role.
          $ref: '#/components/schemas/Reference'
    RoleWithScope:
      type: object
      title: RoleScope
      description: Role along with the scope they are applicable for.
      required:
        - role
        - scope
      properties:
        role:
          $ref: '#/components/schemas/RoleV3'
        scope:
          $ref: '#/components/schemas/Scope'
    Scope:
      type: object
      title: Scope
      description: The set of resources or the resource group that the role applies to.
      required:
        - audiences
      properties:
        audiences:
          type: array
          items:
            $ref: '#/components/schemas/ScopeAudience'
          minItems: 1
    ScopeAudience:
      type: object
      title: ScopeAudience
      description: The audience that the scope audience applies to.
      required:
        - predicates
      properties:
        predicates:
          type: array
          items:
            $ref: '#/components/schemas/AudiencePredicate'
          minItems: 1
    ScopeEntitiesComparator:
      type: string
      description: The comparator to compare scope entity values.
      enum:
        - IN
    ScopeEntityType:
      title: ScopeEntityType
      description: Entity type enum.
      type: string
      enum:
        - PROFILE
        - LEGAL_ENTITY
        - COMPANY
        - PNR
        - TRIP
        - EVENT
        - TRIP_TEMPLATE
        - PLATFORM
      example: LEGAL_ENTITY
    ScopePredicateType:
      type: string
      title: ScopePredicateType
      description: Type of scope predicate.
      enum:
        - PLATFORM
        - BOOKING_TMC
        - CONTRACTING_TMC
        - COMPANY
        - TRIP_TEMPLATE
        - STEALTH_TYPE
      example: CONTRACTING_TMC
    ScopePredicateValue:
      type: object
      title: ScopePredicateValue
      description: A permitted value for a scope predicate type.
      required:
        - value
      properties:
        value:
          type: string
          description: The predicate value identifier.
          example: STEALTH_TYPE_1
        label:
          type: string
          description: Readable label for the value.
          example: VIP Travel
    SortOrder:
      type: string
      description: Sorting order.
      enum:
        - DESC
        - ASC
      example: DESC
      default: ASC
    StealthType:
      type: string
      description: Stealth type.
      enum:
        - STEALTH_TYPE_1
        - STEALTH_TYPE_2
        - STEALTH_TYPE_3
      example: STEALTH_TYPE_1
      x-ignoreBreakingChanges:
        - StealthType->STEALTH_TYPE_4
        - StealthType->STEALTH_TYPE_5
        - StealthType->STEALTH_TYPE_6
    StealthTypePredicate:
      type: object
      title: StealthTypePredicate
      description: Compare the traveler's stealth type with the values.
      required:
        - type
        - comparator
        - values
      properties:
        type:
          type: string
          default: STEALTH_TYPE
        comparator:
          $ref: '#/components/schemas/ScopeEntitiesComparator'
        values:
          type: array
          description: List of stealth types to compare.
          minItems: 1
          items:
            $ref: '#/components/schemas/StealthType'
    TripTemplatePredicate:
      type: object
      title: TripTemplatePredicate
      description: Compare the trip's template id with the values.
      required:
        - type
        - comparator
        - values
      properties:
        type:
          type: string
          default: TRIP_TEMPLATE
        comparator:
          $ref: '#/components/schemas/ScopeEntitiesComparator'
        values:
          type: array
          description: List of trip template ids to compare.
          minItems: 1
          items:
            type: string
        valuesWithLabel:
          type: array
          description: Values with labels
          minItems: 1
          items:
            $ref: '#/components/schemas/NonUuidReference'
    UpdateRoleRequest:
      type: object
      title: UpdateRoleRequest
      description: Role update request.
      required:
        - name
        - description
        - permissions
      properties:
        name:
          type: string
          description: Name of the role.
          example: User Admin
        description:
          type: string
          description: A short description of the role mentioning what can it do.
          example: Manage users for the company.
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/PermissionWithActions'
          description: Permissions granted to the role.
    UpdateRolesRequest:
      type: object
      title: UpdateRolesRequest
      description: Update roles request for a principal.
      properties:
        rolesToAdd:
          type: array
          description: List of roles to be assigned to a principal.
          items:
            $ref: '#/components/schemas/RoleRefWithScope'
          default: []
        rolesToDelete:
          type: array
          description: List of roles to be removed for a principal.
          items:
            type: string
            format: uuid
          default: []
    UpdateUserGroupMembersRequest:
      type: object
      title: UpdateUserGroupMembersRequest
      description: Update user group members request.
      required:
        - userIdsToAdd
        - userIdsToRemove
      properties:
        userIdsToAdd:
          type: array
          description: List of user ids to be added to the user group.
          items:
            type: string
            format: uuid
          example:
            - 1234a66b-7493-4f41-908c-58ba81093947
        userIdsToRemove:
          type: array
          description: List of user ids to be removed from the user group.
          items:
            type: string
            format: uuid
          example:
            - 4974a66b-7493-4f41-908c-58ba81093947
    UserGroupMember:
      type: object
      title: UserGroupMember
      description: User group member information.
      required:
        - userId
        - addedAt
      properties:
        userId:
          type: string
          format: uuid
          description: The ID of the user who is a member of the group.
          example: 1234a66b-7493-4f41-908c-58ba81093947
        addedAt:
          description: The date and time when the user was added to the group.
          $ref: '#/components/schemas/DateTimeOffset'
    UserGroupMemberSortField:
      type: string
      title: UserGroupMemberSortField
      description: The field name to sort user group members.
      enum:
        - ADDED_AT
      default: ADDED_AT
    UserGroupMemberSortParams:
      type: object
      title: UserGroupMemberSortParams
      description: Sorting related parameters to return sorted list of user group members.
      required:
        - sortBy
        - sortOrder
      properties:
        sortBy:
          $ref: '#/components/schemas/UserGroupMemberSortField'
        sortOrder:
          $ref: '#/components/schemas/SortOrder'
    UserGroupSortField:
      type: string
      title: UserGroupSortField
      description: The field name to sort user groups.
      enum:
        - NAME
        - CREATED_AT
      default: NAME
    UserGroupSortParams:
      type: object
      title: UserGroupSortParams
      description: Sorting related parameters to return sorted list of user groups.
      required:
        - sortBy
        - sortOrder
      properties:
        sortBy:
          $ref: '#/components/schemas/UserGroupSortField'
        sortOrder:
          $ref: '#/components/schemas/SortOrder'
    UserGroupUpdateRequest:
      type: object
      title: UserGroupUpdateRequest
      description: User group update request
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: Name of the user group.
          example: Company Admins
        description:
          type: string
          description: A description of the user group.
          example: Group for managing the company settings.
tags:
  - name: User Groups
    description: APIs to manage use groups.
  - name: Roles
    description: APIs to manage roles.
paths:
  /v3/permissions:
    get:
      tags:
        - Roles
      summary: List all permissions on the platform
      description: >-
        This endpoint returns all available permissions on the platform for
        display purposes.
      operationId: listPermissions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPermissionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/{companyId}/permissions:
    parameters:
      - name: companyId
        in: path
        description: Identifier of the company.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093947
    get:
      tags:
        - Roles
      summary: List permissions for a company
      description: This endpoint returns all available permissions for a company.
      operationId: listCompanyPermissions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPermissionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/companies/{companyId}/roles:
    parameters:
      - name: companyId
        in: path
        description: Identifier of the company.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
        - Roles
      summary: List user roles for company
      description: This endpoint provides list of available user roles for a company.
      operationId: listRolesV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListRolesRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRolesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/roles:
    post:
      tags:
        - Roles
      summary: Create role
      description: This endpoint is used to create user roles.
      operationId: createRoleV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/roles/{roleId}:
    parameters:
      - name: roleId
        in: path
        description: Identifier for role.
        required: true
        schema:
          type: string
          format: uuid
        example: 4974a66b-7493-4f41-908c-58ba81093947
    get:
      tags:
        - Roles
      summary: Get role
      description: This endpoint returns role details for given role ID.
      operationId: getRoleV3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleV3'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Roles
      summary: Delete role
      description: This endpoint deletes a role by role ID.
      operationId: deleteRoleV3
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      tags:
        - Roles
      summary: Update role
      operationId: updateRoleV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoleRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/companies/{companyId}/user-groups/list:
    parameters:
      - name: companyId
        in: path
        description: Identifier of the company.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
        - User Groups
      summary: List user groups for company
      description: >-
        This endpoint provides list of user groups of a company, with filtering,
        sorting, and pagination support.
      operationId: listUserGroupsForCompany
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUserGroupsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserGroupsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/{companyId}/user-groups:
    parameters:
      - name: companyId
        in: path
        description: Company ID of the user group.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093653
    post:
      tags:
        - User Groups
      summary: Create user group
      description: This endpoint is used to create user groups.
      operationId: createUserGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserGroupUpdateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/{companyId}/user-groups/{groupId}:
    parameters:
      - name: companyId
        in: path
        description: Company ID of the user group.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093653
      - name: groupId
        in: path
        description: Identifier for the user group.
        required: true
        schema:
          type: string
          format: uuid
        example: 4974a66b-7493-4f41-908c-58ba81093947
    get:
      tags:
        - User Groups
      summary: Read user group
      description: This endpoint returns user group information for given group ID.
      operationId: getUserGroup
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleUserGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - User Groups
      summary: Delete user group
      description: This endpoint deletes a user group by ID.
      operationId: deleteUserGroup
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      tags:
        - User Groups
      summary: Update user group
      operationId: updateUserGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserGroupUpdateRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/companies/{companyId}/user-groups/{groupId}/members:
    parameters:
      - name: companyId
        in: path
        description: Company ID of the user group.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093653
      - name: groupId
        in: path
        description: Identifier for the user group.
        required: true
        schema:
          type: string
          format: uuid
        example: 4974a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
        - User Groups
      summary: List user group members
      description: >-
        This endpoint provides a list of members in a user group with filtering,
        sorting, and pagination support.
      operationId: listUserGroupMembers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUserGroupMembersRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserGroupMembersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - User Groups
      summary: Update user group members
      description: This endpoint updates the members of a user group.
      operationId: updateUserGroupMembers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserGroupMembersRequest'
      responses:
        '200':
          description: Updated Successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/users/{userId}/user-groups:
    parameters:
      - name: userId
        in: path
        description: Identifier of the user.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
        - User Groups
      summary: List user groups for user
      description: >-
        This endpoint provides list of user groups of a user, with filtering,
        sorting, and pagination support.
      operationId: listUserGroupsForUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUserGroupsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserGroupsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v3/companies/{companyId}/roles/applicable-scopes:
    parameters:
      - name: companyId
        in: path
        description: Identifier of the company.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
        - Roles
      summary: Get applicable scopes for selected roles.
      description: >-
        Returns the applicable scope predicate types and their permitted values
        for the selected roles within a company.
      operationId: getApplicableScopes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetApplicableScopesRequest'
      responses:
        '200':
          description: Applicable scopes for the selected roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApplicableScopesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/companies/{companyId}/user-groups/{groupId}/roles:
    parameters:
      - name: companyId
        in: path
        description: Company ID of the user group.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093653
      - name: groupId
        in: path
        description: Identifier for the user group.
        required: true
        schema:
          type: string
          format: uuid
        example: 4974a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
        - Roles
      summary: List user group roles
      description: This endpoint provides list of roles assigned to the usergroup.
      operationId: listUserGroupRolesV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUserGroupRolesRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserGroupRolesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    patch:
      tags:
        - Roles
      summary: Update user group roles
      description: This endpoint updates roles assigned to a usergroup.
      operationId: updateUserGroupRolesV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRolesRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/users/{userId}/roles:
    parameters:
      - name: userId
        in: path
        description: Identifier of the user.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
        - Roles
      summary: List user roles
      description: This endpoint provides list of roles assigned to the user.
      operationId: listUserRolesV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListUserRolesRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserRolesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    patch:
      tags:
        - Roles
      summary: Update user roles
      description: This endpoint updates roles assigned to a user.
      operationId: updateUserRolesV3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRolesRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/users/{userId}/entity-permissions:
    parameters:
      - name: userId
        in: path
        description: User ID
        required: true
        schema:
          type: string
          format: uuid
          example: f49d00fe-1eda-4304-ba79-a980f565281d
    post:
      tags:
        - Roles
      summary: Get user permissions on specific entity.
      description: Returns user's permissions with actions on a specified entity.
      operationId: getEntityPermissions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetEntityPermissionsRequest'
      responses:
        '200':
          description: List of permissions user has on the entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEntityPermissionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v3/users/{userId}/rbac-info:
    parameters:
      - name: userId
        in: path
        description: Identifier of the user.
        required: true
        schema:
          type: string
          format: uuid
        example: 1234a66b-7493-4f41-908c-58ba81093947
    get:
      tags:
        - Roles
      summary: Get RBAC info for a user
      description: >-
        Returns RBAC information for a user indicating what permissions the user
        has.
      operationId: getRbacInfo
      responses:
        '200':
          description: RBAC info for the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRbacInfoResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
