openapi: 3.0.3
info:
  title: Entrosity Vertex Portal API
  version: 0.1.0
  description: |
    Entrosity Vertex portal REST API: Active Directory management per
    tenant — users (every attribute), groups and membership, OUs, Group
    Policy Objects (links, registry settings, security filtering),
    fine-grained password policies and CSV bulk imports. Vertex reaches
    the directory through the tenant's Entrosity Axis connector on a
    domain controller. This file is the source of truth for the backend
    server interfaces (oapi-codegen), request validation, and the frontend
    types (openapi-typescript). Run `make gen` after editing.

    Authentication: `Authorization: Bearer <product token>`: users sign in
    on Entrosity Hub, which issues five-minute product tokens for Vertex
    (`POST /api/platform/v1/auth/product-token {"product":"vertex"}`, with the
    Hub's session cookie). Users, tenants (the Hub's organizations) and
    roles are managed on the Hub; Vertex keeps a copy.

    Reads of lists come from Vertex's mirror of the directory (refreshed by
    syncs and after every change). Every change is an asynchronous
    **operation**: the API answers `202` with the operation, which the
    connector runs; follow it with `GET /tenants/{t}/operations/{id}?wait=20`
    or the `vertex.operation` event of the live stream.

    Every route's access rule (public, authenticated, global admin, tenant
    permission) is declared in `internal/http/portal/access.go` and enforced
    before the handler runs.
servers:
  - url: /api/v1
tags:
  - name: system
  - name: auth
  - name: admin
  - name: tenant
  - name: directory
  - name: users
  - name: groups
  - name: objects
  - name: gpos
  - name: password-policies
  - name: imports
  - name: operations
  - name: events
security:
  - bearerAuth: []
paths:
  /healthz:
    get:
      operationId: getHealthz
      summary: Liveness probe
      tags:
        - system
      security: []
      responses:
        '200':
          description: The API process is up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
        default:
          $ref: '#/components/responses/Problem'
  /auth/sse-token:
    post:
      operationId: createStreamToken
      summary: Short-lived token for a tenant live stream (EventSource)
      description: |
        Returns a token valid for 60 seconds that opens
        `GET /tenants/{tenantID}/stream?sse_token=` for the given tenant and
        the caller's session. Access to the tenant is checked when the
        stream opens. Keeps the access token out of URLs.
      tags:
        - auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - tenant_id
              properties:
                tenant_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Stream token.
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                  - expires_in
                properties:
                  token:
                    type: string
                  expires_in:
                    type: integer
                    description: Seconds.
        default:
          $ref: '#/components/responses/Problem'
  /me:
    get:
      operationId: getMe
      summary: The signed-in user with their tenants and roles
      tags:
        - auth
      responses:
        '200':
          description: Current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
        default:
          $ref: '#/components/responses/Problem'
  /admin/overview:
    get:
      operationId: getAdminOverview
      summary: Cross-tenant counters
      tags:
        - admin
      responses:
        '200':
          description: Overview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminOverview'
        default:
          $ref: '#/components/responses/Problem'
  /admin/tenants:
    get:
      operationId: listTenants
      summary: List tenants
      tags:
        - admin
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Query'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/TenantStatus'
      responses:
        '200':
          description: Tenants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantList'
        default:
          $ref: '#/components/responses/Problem'
  /admin/users:
    get:
      operationId: listGlobalAdmins
      summary: Global admins (the platform admins of Entrosity Hub)
      tags:
        - admin
      responses:
        '200':
          description: Users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDirectory'
        default:
          $ref: '#/components/responses/Problem'
  /admin/audit:
    get:
      operationId: listAdminAudit
      summary: Cross-tenant audit log
      tags:
        - admin
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: tenant_id
          in: query
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/AuditActor'
        - $ref: '#/components/parameters/AuditAction'
        - $ref: '#/components/parameters/AuditResourceType'
        - $ref: '#/components/parameters/AuditFrom'
        - $ref: '#/components/parameters/AuditTo'
      responses:
        '200':
          description: Audit entries, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditList'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: getTenant
      summary: Tenant profile
      tags:
        - tenant
      responses:
        '200':
          description: Tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        default:
          $ref: '#/components/responses/Problem'
    patch:
      operationId: updateTenant
      summary: Change the tenant's settings (the name is the Hub's)
      tags:
        - tenant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTenantRequest'
      responses:
        '200':
          description: Updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/members:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listTenantMembers
      summary: Tenant members and their Vertex roles (managed on Entrosity Hub)
      tags:
        - tenant
      responses:
        '200':
          description: Users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDirectory'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/audit:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listTenantAudit
      summary: Audit log of the tenant
      tags:
        - tenant
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/AuditActor'
        - $ref: '#/components/parameters/AuditAction'
        - $ref: '#/components/parameters/AuditResourceType'
        - $ref: '#/components/parameters/AuditFrom'
        - $ref: '#/components/parameters/AuditTo'
      responses:
        '200':
          description: Audit entries, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditList'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/stream:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: streamTenantEvents
      summary: Live updates (server-sent events)
      description: |
        `text/event-stream` of the tenant's live updates:
        `vertex.operation` (an `Operation` changed: queued, progress,
        finished), `vertex.directory` (`{kinds: [...]}`: the mirror changed,
        reload those lists), `vertex.import` (`{import_id}`: a bulk import
        progressed) and `vertex.settings`. Authenticate with a bearer token
        or, for EventSource, `?sse_token=` from `POST /auth/sse-token`.
      tags:
        - events
      parameters:
        - name: sse_token
          in: query
          schema:
            type: string
            maxLength: 4096
      responses:
        '200':
          description: Event stream.
          content:
            text/event-stream:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/directory/settings:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: getDirectorySettings
      summary: The tenant's directory settings (the AD password is never returned)
      tags:
        - directory
      responses:
        '200':
          description: Settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectorySettings'
        default:
          $ref: '#/components/responses/Problem'
    put:
      operationId: putDirectorySettings
      summary: Set the connector, AD account, managed OUs and write switches
      description: |
        Needs a `step_up_token` (Entrosity Hub re-authentication). Leave
        `ad_password` out to keep the stored one. Write switches are off by
        default; even when on, the connector's local guard on the domain
        controller must allow the same kind of change.
      tags:
        - directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutDirectorySettingsRequest'
      responses:
        '200':
          description: Saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectorySettings'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/directory/connectors:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listDirectoryConnectors
      summary: The tenant's Entrosity Axis connectors (which can run Vertex jobs)
      tags:
        - directory
      responses:
        '200':
          description: Connectors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorList'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/directory/test:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    post:
      operationId: testDirectory
      summary: Check the AD account, the domain and the PowerShell modules
      tags:
        - directory
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/directory/sync:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    post:
      operationId: syncDirectory
      summary: Read users, groups, OUs, password policies and GPOs now
      tags:
        - directory
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/directory/overview:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: getDirectoryOverview
      summary: Counters of the mirror, the last sync and the recent operations
      tags:
        - directory
      responses:
        '200':
          description: Overview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryOverview'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/directory/schema:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listDirectorySchema
      summary: Attributes of users, groups and OUs (for the attribute editor)
      tags:
        - directory
      parameters:
        - name: class
          in: query
          schema:
            type: string
            enum:
              - user
              - group
              - organizationalUnit
      responses:
        '200':
          description: Attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeSchemaList'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/directory/schema/refresh:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    post:
      operationId: refreshDirectorySchema
      summary: Read the attribute schema from the directory again
      tags:
        - directory
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/users:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listADUsers
      summary: Directory users (from the mirror)
      tags:
        - users
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/OUFilter'
        - name: enabled
          in: query
          schema:
            type: boolean
        - name: locked
          in: query
          schema:
            type: boolean
        - name: member_of
          in: query
          description: DN of a group the users are direct members of.
          schema:
            type: string
            maxLength: 2048
      responses:
        '200':
          description: Users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryObjectList'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createADUser
      summary: Create a user
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/users/{objectID}/password:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    post:
      operationId: resetADUserPassword
      summary: Set a new password (optionally require a change at next logon, unlock)
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/users/{objectID}/unlock:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    post:
      operationId: unlockADUser
      summary: Unlock a locked-out user
      tags:
        - users
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/users/{objectID}/enabled:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    put:
      operationId: setADUserEnabled
      summary: Enable or disable a user
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEnabledRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/users/{objectID}/groups:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    post:
      operationId: changeADUserGroups
      summary: >-
        Add the user to groups and remove them from others (one operation per
        group)
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeUserGroupsRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationsAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/users/bulk-actions:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    post:
      operationId: bulkADUserAction
      summary: >-
        The same action on many users (one operation per user, or per group for
        membership)
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUserActionRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationsAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/groups:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listADGroups
      summary: Directory groups (from the mirror)
      tags:
        - groups
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/OUFilter'
      responses:
        '200':
          description: Groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryObjectList'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createADGroup
      summary: Create a group
      tags:
        - groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/groups/{objectID}/members:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    get:
      operationId: listADGroupMembers
      summary: Direct members of a group (from the mirror)
      tags:
        - groups
      responses:
        '200':
          description: Members (objects outside the mirror have only their DN).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMembers'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: changeADGroupMembers
      summary: Add and remove members (DNs)
      tags:
        - groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeMembersRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/ous:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listADOUs
      summary: Organizational units (and the domain), with their GPO links
      tags:
        - objects
      responses:
        '200':
          description: OUs, parents before children.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OUList'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createADOU
      summary: Create an organizational unit
      tags:
        - objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOURequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/objects/{objectID}:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    get:
      operationId: getADObject
      summary: A user, group, OU or password policy with every mirrored attribute
      tags:
        - objects
      responses:
        '200':
          description: Object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryObject'
        default:
          $ref: '#/components/responses/Problem'
    patch:
      operationId: updateADObject
      summary: Set, add, remove or clear attributes
      description: |
        Attribute names are LDAP display names. Values are strings
        (binary as `b64:<base64>`). Identity, security and membership
        attributes are refused (dedicated endpoints exist). The helpdesk
        role may change contact attributes of users only.
      tags:
        - objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateObjectRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: deleteADObject
      summary: Delete a user, group, OU or password policy
      description: Needs a step-up token (header `X-Step-Up-Token`) and the deletes switch.
      tags:
        - objects
      parameters:
        - $ref: '#/components/parameters/StepUpHeader'
        - name: recursive
          in: query
          description: OUs only — delete everything below as well.
          schema:
            type: boolean
            default: false
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/objects/{objectID}/refresh:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    post:
      operationId: refreshADObject
      summary: >-
        Read the object live with all attributes (and which ones the AD account
        may write)
      tags:
        - objects
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/objects/{objectID}/move:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    post:
      operationId: moveADObject
      summary: Move to another OU
      tags:
        - objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/objects/{objectID}/rename:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    post:
      operationId: renameADObject
      summary: Rename (the CN / OU name)
      tags:
        - objects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/password-policies:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listPasswordPolicies
      summary: Fine-grained password policies (PSOs)
      tags:
        - password-policies
      responses:
        '200':
          description: Policies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordPolicyList'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createPasswordPolicy
      summary: Create a password policy
      tags:
        - password-policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePasswordPolicyRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/password-policies/{objectID}:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ObjectID'
    patch:
      operationId: updatePasswordPolicy
      summary: Change settings and whom the policy applies to
      tags:
        - password-policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePasswordPolicyRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/gpos:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listGPOs
      summary: Group Policy Objects
      tags:
        - gpos
      parameters:
        - $ref: '#/components/parameters/Query'
      responses:
        '200':
          description: GPOs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GPOList'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createGPO
      summary: Create a GPO (optionally linked to an OU)
      tags:
        - gpos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGPORequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/gpos/{gpoID}:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/GPOID'
    get:
      operationId: getGPO
      summary: A GPO with the OUs it is linked to
      tags:
        - gpos
      responses:
        '200':
          description: GPO.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GPODetail'
        default:
          $ref: '#/components/responses/Problem'
    patch:
      operationId: updateGPO
      summary: Rename, change the status or the comment
      tags:
        - gpos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGPORequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
    delete:
      operationId: deleteGPO
      summary: Delete a GPO (backed up first on the domain controller)
      tags:
        - gpos
      parameters:
        - $ref: '#/components/parameters/StepUpHeader'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/gpos/{gpoID}/report:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/GPOID'
    get:
      operationId: getGPOReport
      summary: The last read XML report of the GPO (all its settings)
      tags:
        - gpos
      responses:
        '200':
          description: Report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GPOReport'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: refreshGPOReport
      summary: Read the GPO's report from the domain controller
      tags:
        - gpos
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/gpos/{gpoID}/links:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/GPOID'
    post:
      operationId: changeGPOLink
      summary: Link, unlink or change a link (enabled, enforced, order)
      tags:
        - gpos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GPOLinkRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/gpos/{gpoID}/registry:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/GPOID'
    post:
      operationId: changeGPORegistry
      summary: Set or remove registry-based policy settings
      tags:
        - gpos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GPORegistryRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/gpos/{gpoID}/permissions:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/GPOID'
    post:
      operationId: setGPOPermission
      summary: Security filtering and delegation (one trustee)
      tags:
        - gpos
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GPOPermissionRequest'
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/gpos/{gpoID}/backup:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/GPOID'
    post:
      operationId: backupGPO
      summary: Back the GPO up on the domain controller
      tags:
        - gpos
      responses:
        '202':
          $ref: '#/components/responses/OperationAccepted'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/imports:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listImports
      summary: Bulk imports of users
      tags:
        - imports
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Imports, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkImportList'
        default:
          $ref: '#/components/responses/Problem'
    post:
      operationId: createImport
      summary: Upload a CSV and validate it (nothing changes until commit)
      description: |
        The CSV (UTF-8, comma or semicolon separated, header row) is parsed
        and every row checked against the mirror: `create` (new logon
        name), `update` (existing user) or `invalid` (with the problems).
        Columns: `sAMAccountName` (required), `password`, `ou`, `name`,
        `givenName`, `sn`, `displayName`, `userPrincipalName`, `mail`,
        `enabled`, `mustChangePassword`, `groups` (`;`-separated DNs or
        group names), the common attributes by their LDAP names, and any
        other attribute as `attr:<ldapName>`. Passwords are kept encrypted
        until the import ends and never shown again.
      tags:
        - imports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImportRequest'
      responses:
        '201':
          description: Validated import (preview).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkImport'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/imports/template:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: getImportTemplate
      summary: An example CSV with the supported columns
      tags:
        - imports
      responses:
        '200':
          description: CSV.
          content:
            text/csv:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/imports/{importID}:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ImportID'
    get:
      operationId: getImport
      summary: An import with its counters
      tags:
        - imports
      responses:
        '200':
          description: Import.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkImport'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/imports/{importID}/rows:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ImportID'
    get:
      operationId: listImportRows
      summary: Rows of an import (preview before, results after commit)
      tags:
        - imports
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/ImportRowStatus'
        - name: action
          in: query
          schema:
            $ref: '#/components/schemas/ImportRowAction'
      responses:
        '200':
          description: Rows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportRowList'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/imports/{importID}/commit:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ImportID'
    post:
      operationId: commitImport
      summary: Apply the valid rows (invalid rows are skipped)
      tags:
        - imports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepUpRequest'
      responses:
        '200':
          description: Running import.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkImport'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/imports/{importID}/cancel:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ImportID'
    post:
      operationId: cancelImport
      summary: Discard a validated import (and its passwords)
      tags:
        - imports
      responses:
        '200':
          description: Cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkImport'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/imports/{importID}/result.csv:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/ImportID'
    get:
      operationId: getImportResultCSV
      summary: Every row with its outcome (never contains passwords)
      tags:
        - imports
      responses:
        '200':
          description: CSV.
          content:
            text/csv:
              schema:
                type: string
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/operations:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    get:
      operationId: listOperations
      summary: Operations (changes and reads), newest first
      tags:
        - operations
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: target_id
          in: query
          description: Object GUID or GPO id.
          schema:
            type: string
            maxLength: 64
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OperationStatus'
        - name: class
          in: query
          schema:
            $ref: '#/components/schemas/OperationClass'
        - name: changes_only
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Operations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationList'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/operations/{operationID}:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/OperationID'
    get:
      operationId: getOperation
      summary: >-
        One operation; with `wait`, answers as soon as it finished (or after
        `wait` seconds)
      tags:
        - operations
      parameters:
        - name: wait
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 25
            default: 0
      responses:
        '200':
          description: Operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          $ref: '#/components/responses/Problem'
  /tenants/{tenantID}/operations/{operationID}/cancel:
    parameters:
      - $ref: '#/components/parameters/TenantID'
      - $ref: '#/components/parameters/OperationID'
    post:
      operationId: cancelOperation
      summary: Cancel an operation that has not finished (best effort once running)
      tags:
        - operations
      responses:
        '200':
          description: Operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          $ref: '#/components/responses/Problem'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    TenantID:
      name: tenantID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ObjectID:
      name: objectID
      in: path
      required: true
      description: The object's GUID (objectGUID).
      schema:
        type: string
        format: uuid
    GPOID:
      name: gpoID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ImportID:
      name: importID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    OperationID:
      name: operationID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    StepUpHeader:
      name: X-Step-Up-Token
      in: header
      description: >-
        Step-up token from Entrosity Hub (re-authentication), used once.
        Required (checked after authentication).
      schema:
        type: string
        minLength: 1
        maxLength: 4096
    OUFilter:
      name: ou
      in: query
      description: DN of an OU; only objects below it.
      schema:
        type: string
        maxLength: 2048
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100000
        default: 1
    PageSize:
      name: page_size
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 50
    Query:
      name: q
      in: query
      schema:
        type: string
        maxLength: 200
    AuditActor:
      name: actor_user_id
      in: query
      schema:
        type: string
        format: uuid
    AuditAction:
      name: action
      in: query
      schema:
        type: string
        maxLength: 100
    AuditResourceType:
      name: resource_type
      in: query
      schema:
        type: string
        maxLength: 100
    AuditFrom:
      name: from
      in: query
      schema:
        type: string
        format: date-time
    AuditTo:
      name: to
      in: query
      schema:
        type: string
        format: date-time
  responses:
    Problem:
      description: Error (RFC 7807).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    OperationAccepted:
      description: The operation was queued for the connector.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Operation'
    OperationsAccepted:
      description: The operations were queued for the connector.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationBatch'
  schemas:
    Health:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - ok
    Problem:
      type: object
      description: RFC 7807 problem details.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          description: URI reference identifying the problem type.
          example: about:blank
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: Stable machine-readable error code, e.g. connector_offline.
        instance:
          type: string
        request_id:
          type: string
        fields:
          type: object
          description: Per-field validation errors.
          additionalProperties:
            type: string
    Role:
      type: string
      enum:
        - global_admin
        - tenant_admin
        - helpdesk
    TenantRole:
      type: string
      enum:
        - tenant_admin
        - helpdesk
    UserStatus:
      type: string
      enum:
        - active
        - disabled
        - deleted
    TenantStatus:
      type: string
      enum:
        - active
        - suspended
    User:
      type: object
      required:
        - id
        - email
        - display_name
        - role
        - tenant_id
        - status
        - created_at
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
        display_name:
          type: string
        role:
          $ref: '#/components/schemas/Role'
        tenant_id:
          type: string
          format: uuid
          nullable: true
        status:
          $ref: '#/components/schemas/UserStatus'
        created_at:
          type: string
          format: date-time
    Me:
      type: object
      description: >-
        The signed-in user. A user can belong to several tenants, with one role
        in each; global admins have every permission in every tenant.
      required:
        - id
        - email
        - display_name
        - status
        - is_global_admin
        - memberships
        - created_at
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
        display_name:
          type: string
        status:
          $ref: '#/components/schemas/UserStatus'
        is_global_admin:
          type: boolean
        memberships:
          type: array
          items:
            $ref: '#/components/schemas/TenantMembership'
        created_at:
          type: string
          format: date-time
    TenantMembership:
      type: object
      required:
        - tenant_id
        - tenant_name
        - tenant_status
        - role
      properties:
        tenant_id:
          type: string
          format: uuid
        tenant_name:
          type: string
        tenant_status:
          $ref: '#/components/schemas/TenantStatus'
        role:
          $ref: '#/components/schemas/TenantRole'
    UserDirectory:
      type: object
      required:
        - users
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Tenant:
      type: object
      required:
        - id
        - name
        - slug
        - status
        - settings
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        status:
          $ref: '#/components/schemas/TenantStatus'
        settings:
          $ref: '#/components/schemas/TenantSettings'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TenantRetention:
      type: object
      additionalProperties: false
      description: Overrides of the server's retention windows (sent as a whole).
      properties:
        job_days:
          type: integer
          minimum: 7
          maximum: 730
          description: Finished operations.
        audit_days:
          type: integer
          minimum: 30
          maximum: 3650
          description: Audit log entries.
    TenantSettings:
      type: object
      additionalProperties: false
      properties:
        retention:
          $ref: '#/components/schemas/TenantRetention'
    TenantList:
      type: object
      required:
        - items
        - page
        - page_size
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tenant'
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
    UpdateTenantRequest:
      type: object
      additionalProperties: false
      properties:
        settings:
          $ref: '#/components/schemas/TenantSettings'
    AdminOverview:
      type: object
      required:
        - tenants_total
        - tenants_active
        - global_admins
        - tenant_users
        - tenants
      properties:
        tenants_total:
          type: integer
        tenants_active:
          type: integer
        global_admins:
          type: integer
        tenant_users:
          type: integer
        tenants:
          type: array
          items:
            $ref: '#/components/schemas/TenantVertexCounts'
    TenantVertexCounts:
      type: object
      required:
        - tenant_id
        - name
        - status
        - configured
        - users
        - groups
        - last_sync_at
        - last_sync_status
      properties:
        tenant_id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
        configured:
          type: boolean
          description: A connector and an AD account are set.
        users:
          type: integer
        groups:
          type: integer
        last_sync_at:
          type: string
          format: date-time
          nullable: true
        last_sync_status:
          type: string
    AuditEntry:
      type: object
      required:
        - id
        - ts
        - tenant_id
        - actor_user_id
        - actor_email
        - action
        - resource_type
        - resource_id
        - before
        - after
        - ip
        - request_id
      properties:
        id:
          type: string
          format: uuid
        ts:
          type: string
          format: date-time
        tenant_id:
          type: string
          format: uuid
          nullable: true
        actor_user_id:
          type: string
          format: uuid
          nullable: true
        actor_email:
          type: string
        action:
          type: string
        resource_type:
          type: string
        resource_id:
          type: string
        before:
          type: object
          nullable: true
          additionalProperties: true
        after:
          type: object
          nullable: true
          additionalProperties: true
        ip:
          type: string
        request_id:
          type: string
    AuditList:
      type: object
      required:
        - items
        - page
        - page_size
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditEntry'
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
    WriteSwitches:
      type: object
      description: >-
        What Vertex may change (all off by default). The connector's local guard
        must allow it too.
      required:
        - users
        - groups
        - ous
        - gpos
        - password_policies
        - deletes
      properties:
        users:
          type: boolean
        groups:
          type: boolean
        ous:
          type: boolean
        gpos:
          type: boolean
        password_policies:
          type: boolean
        deletes:
          type: boolean
    DomainInfo:
      type: object
      description: What the last directory test found.
      properties:
        domain:
          type: string
        domain_dn:
          type: string
        netbios_name:
          type: string
        domain_mode:
          type: string
        domain_controller:
          type: string
        account:
          type: string
        modules:
          type: array
          items:
            type: string
        pso_container_dn:
          type: string
        managed_ous_ok:
          type: array
          items:
            type: string
        managed_ous_missing:
          type: array
          items:
            type: string
        upn_suffixes:
          type: array
          items:
            type: string
    DirectorySettings:
      type: object
      required:
        - configured
        - connector_id
        - server
        - ad_username
        - has_password
        - managed_ous
        - default_user_ou
        - upn_suffix
        - user_attributes
        - sync_interval_minutes
        - writes
        - domain
        - last_test_at
        - last_sync_at
        - last_sync_status
        - last_sync_error
        - next_sync_at
      properties:
        configured:
          type: boolean
        connector_id:
          type: string
          format: uuid
          nullable: true
        server:
          type: string
          description: Domain controller to use (empty = the connector's).
        ad_username:
          type: string
        has_password:
          type: boolean
        managed_ous:
          type: array
          items:
            type: string
        default_user_ou:
          type: string
        upn_suffix:
          type: string
        user_attributes:
          type: array
          items:
            type: string
          description: Extra attributes read for every user by syncs.
        sync_interval_minutes:
          type: integer
        writes:
          $ref: '#/components/schemas/WriteSwitches'
        domain:
          allOf:
            - $ref: '#/components/schemas/DomainInfo'
          nullable: true
        last_test_at:
          type: string
          format: date-time
          nullable: true
        last_sync_at:
          type: string
          format: date-time
          nullable: true
        last_sync_status:
          type: string
        last_sync_error:
          type: string
        next_sync_at:
          type: string
          format: date-time
          nullable: true
    PutDirectorySettingsRequest:
      type: object
      additionalProperties: false
      required:
        - connector_id
        - ad_username
        - managed_ous
        - writes
        - step_up_token
      properties:
        connector_id:
          type: string
          format: uuid
        server:
          type: string
          maxLength: 253
        ad_username:
          type: string
          minLength: 1
          maxLength: 256
          description: DOMAIN\name or name@domain
        ad_password:
          type: string
          minLength: 1
          maxLength: 256
          description: Leave out to keep the stored password.
        managed_ous:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 2048
        default_user_ou:
          type: string
          maxLength: 2048
        upn_suffix:
          type: string
          maxLength: 253
        user_attributes:
          type: array
          maxItems: 200
          items:
            type: string
            maxLength: 128
        sync_interval_minutes:
          type: integer
          minimum: 5
          maximum: 1440
          default: 30
        writes:
          $ref: '#/components/schemas/WriteSwitches'
        step_up_token:
          type: string
          minLength: 1
          maxLength: 4096
    Connector:
      type: object
      required:
        - id
        - name
        - hostname
        - domain
        - version
        - status
        - capabilities
        - supports_vertex
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        hostname:
          type: string
        domain:
          type: string
        version:
          type: string
        status:
          type: string
          enum:
            - online
            - offline
        capabilities:
          type: array
          items:
            type: string
        supports_vertex:
          type: boolean
          description: The connector version can run Vertex jobs.
        last_seen_at:
          type: string
          format: date-time
          nullable: true
    ConnectorList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Connector'
    DirectoryOverview:
      type: object
      required:
        - settings
        - users
        - users_disabled
        - users_locked
        - groups
        - ous
        - password_policies
        - gpos
        - operations_open
        - operations_failed_today
        - recent
      properties:
        settings:
          $ref: '#/components/schemas/DirectorySettings'
        users:
          type: integer
        users_disabled:
          type: integer
        users_locked:
          type: integer
        groups:
          type: integer
        ous:
          type: integer
        password_policies:
          type: integer
        gpos:
          type: integer
        operations_open:
          type: integer
        operations_failed_today:
          type: integer
        recent:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
    AttributeSchema:
      type: object
      required:
        - name
        - syntax
        - om_syntax
        - single_valued
        - system_only
        - constructed
        - classes
        - denied
      properties:
        name:
          type: string
        syntax:
          type: string
          description: attributeSyntax OID (2.5.5.x).
        om_syntax:
          type: integer
        single_valued:
          type: boolean
        system_only:
          type: boolean
        constructed:
          type: boolean
        range_lower:
          type: integer
          format: int64
          nullable: true
        range_upper:
          type: integer
          format: int64
          nullable: true
        classes:
          type: array
          items:
            type: string
        denied:
          type: boolean
          description: Vertex never changes it through attribute edits.
    AttributeSchemaList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AttributeSchema'
    ObjectKind:
      type: string
      enum:
        - user
        - group
        - ou
        - pso
    Attributes:
      type: object
      description: Attribute values by LDAP display name (binary as `b64:<base64>`).
      additionalProperties:
        type: array
        items:
          type: string
    DirectoryObjectSummary:
      type: object
      required:
        - id
        - kind
        - dn
        - parent_dn
        - name
        - sam_account_name
        - user_principal_name
        - display_name
        - mail
        - description
        - enabled
        - locked
        - protected
        - in_scope
        - member_of
        - member_count
        - synced_at
      properties:
        id:
          type: string
          format: uuid
        kind:
          $ref: '#/components/schemas/ObjectKind'
        dn:
          type: string
        parent_dn:
          type: string
        name:
          type: string
        sam_account_name:
          type: string
        user_principal_name:
          type: string
        display_name:
          type: string
        mail:
          type: string
        description:
          type: string
        enabled:
          type: boolean
          nullable: true
          description: Users only.
        locked:
          type: boolean
        protected:
          type: boolean
          description: Privileged or built-in; Vertex never changes it.
        in_scope:
          type: boolean
          description: Below a managed OU (changeable).
        member_of:
          type: array
          items:
            type: string
        member_count:
          type: integer
        when_changed:
          type: string
          format: date-time
          nullable: true
        last_logon:
          type: string
          format: date-time
          nullable: true
        synced_at:
          type: string
          format: date-time
    DirectoryObject:
      allOf:
        - $ref: '#/components/schemas/DirectoryObjectSummary'
        - type: object
          required:
            - sid
            - attributes
            - members
            - writable
          properties:
            sid:
              type: string
            attributes:
              $ref: '#/components/schemas/Attributes'
            members:
              type: array
              items:
                type: string
            writable:
              type: array
              items:
                type: string
              description: >-
                Attributes the AD account may write (after a refresh; empty
                before).
    DirectoryObjectList:
      type: object
      required:
        - items
        - page
        - page_size
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DirectoryObjectSummary'
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
    GroupMembers:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
              - dn
            properties:
              dn:
                type: string
              object:
                allOf:
                  - $ref: '#/components/schemas/DirectoryObjectSummary'
                nullable: true
    GPOLinkInfo:
      type: object
      required:
        - gpo_id
        - enabled
        - enforced
        - order
      properties:
        gpo_id:
          type: string
          format: uuid
        gpo_name:
          type: string
        enabled:
          type: boolean
        enforced:
          type: boolean
        order:
          type: integer
          description: 1 = highest precedence.
    OU:
      type: object
      required:
        - id
        - dn
        - parent_dn
        - name
        - description
        - protected
        - in_scope
        - is_domain
        - block_inheritance
        - links
      properties:
        id:
          type: string
          format: uuid
        dn:
          type: string
        parent_dn:
          type: string
        name:
          type: string
        description:
          type: string
        protected:
          type: boolean
        in_scope:
          type: boolean
        is_domain:
          type: boolean
        block_inheritance:
          type: boolean
        links:
          type: array
          items:
            $ref: '#/components/schemas/GPOLinkInfo'
    OUList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OU'
    CreateUserRequest:
      type: object
      additionalProperties: false
      required:
        - sam_account_name
      properties:
        ou:
          type: string
          maxLength: 2048
          description: Default the settings' default user OU.
        name:
          type: string
          maxLength: 64
          description: CN (default "given surname" or the logon name).
        sam_account_name:
          type: string
          minLength: 1
          maxLength: 20
        user_principal_name:
          type: string
          maxLength: 1024
          description: Default logon name @ the UPN suffix.
        given_name:
          type: string
          maxLength: 64
        surname:
          type: string
          maxLength: 64
        display_name:
          type: string
          maxLength: 256
        password:
          type: string
          minLength: 1
          maxLength: 256
          description: Without a password the account is created disabled.
        enabled:
          type: boolean
          default: true
        must_change_password:
          type: boolean
          default: true
        password_never_expires:
          type: boolean
          default: false
        cannot_change_password:
          type: boolean
          default: false
        attributes:
          $ref: '#/components/schemas/Attributes'
        groups:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 2048
          description: Group DNs.
    UpdateObjectRequest:
      type: object
      additionalProperties: false
      properties:
        set:
          $ref: '#/components/schemas/Attributes'
        add:
          $ref: '#/components/schemas/Attributes'
        remove:
          $ref: '#/components/schemas/Attributes'
        clear:
          type: array
          maxItems: 200
          items:
            type: string
            maxLength: 128
    ResetPasswordRequest:
      type: object
      additionalProperties: false
      required:
        - password
      properties:
        password:
          type: string
          minLength: 1
          maxLength: 256
        must_change:
          type: boolean
          default: true
        unlock:
          type: boolean
          default: true
    SetEnabledRequest:
      type: object
      additionalProperties: false
      required:
        - enabled
      properties:
        enabled:
          type: boolean
    ChangeUserGroupsRequest:
      type: object
      additionalProperties: false
      properties:
        add:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 2048
          description: Group DNs.
        remove:
          type: array
          maxItems: 100
          items:
            type: string
            maxLength: 2048
    BulkUserAction:
      type: string
      enum:
        - enable
        - disable
        - unlock
        - move
        - add_to_group
        - remove_from_group
        - delete
    BulkUserActionRequest:
      type: object
      additionalProperties: false
      required:
        - user_ids
        - action
      properties:
        user_ids:
          type: array
          minItems: 1
          maxItems: 500
          items:
            type: string
            format: uuid
        action:
          $ref: '#/components/schemas/BulkUserAction'
        target_ou:
          type: string
          maxLength: 2048
          description: For move.
        group_dn:
          type: string
          maxLength: 2048
          description: For add_to_group / remove_from_group.
        step_up_token:
          type: string
          maxLength: 4096
          description: Required for delete.
    CreateGroupRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - scope
        - category
      properties:
        ou:
          type: string
          maxLength: 2048
        name:
          type: string
          minLength: 1
          maxLength: 64
        sam_account_name:
          type: string
          maxLength: 20
        scope:
          type: string
          enum:
            - DomainLocal
            - Global
            - Universal
        category:
          type: string
          enum:
            - Security
            - Distribution
        description:
          type: string
          maxLength: 1024
        attributes:
          $ref: '#/components/schemas/Attributes'
    ChangeMembersRequest:
      type: object
      additionalProperties: false
      properties:
        add:
          type: array
          maxItems: 500
          items:
            type: string
            maxLength: 2048
        remove:
          type: array
          maxItems: 500
          items:
            type: string
            maxLength: 2048
    CreateOURequest:
      type: object
      additionalProperties: false
      required:
        - parent_dn
        - name
      properties:
        parent_dn:
          type: string
          maxLength: 2048
        name:
          type: string
          minLength: 1
          maxLength: 64
        description:
          type: string
          maxLength: 1024
        protect_from_deletion:
          type: boolean
          default: true
    MoveRequest:
      type: object
      additionalProperties: false
      required:
        - target_ou
      properties:
        target_ou:
          type: string
          minLength: 1
          maxLength: 2048
    RenameRequest:
      type: object
      additionalProperties: false
      required:
        - new_name
      properties:
        new_name:
          type: string
          minLength: 1
          maxLength: 64
    PasswordPolicySettings:
      type: object
      additionalProperties: false
      required:
        - precedence
        - min_password_length
        - password_history_count
        - complexity_enabled
        - reversible_encryption_enabled
        - min_password_age_seconds
        - max_password_age_seconds
        - lockout_threshold
        - lockout_duration_seconds
        - lockout_observation_window_seconds
      properties:
        precedence:
          type: integer
          minimum: 1
        min_password_length:
          type: integer
          minimum: 0
          maximum: 255
        password_history_count:
          type: integer
          minimum: 0
          maximum: 1024
        complexity_enabled:
          type: boolean
        reversible_encryption_enabled:
          type: boolean
        min_password_age_seconds:
          type: integer
          format: int64
          minimum: 0
        max_password_age_seconds:
          type: integer
          format: int64
          minimum: 0
          description: 0 = never expires.
        lockout_threshold:
          type: integer
          minimum: 0
          maximum: 65535
        lockout_duration_seconds:
          type: integer
          format: int64
          minimum: 0
        lockout_observation_window_seconds:
          type: integer
          format: int64
          minimum: 0
    PasswordPolicy:
      type: object
      required:
        - id
        - dn
        - name
        - description
        - settings
        - applies_to
      properties:
        id:
          type: string
          format: uuid
        dn:
          type: string
        name:
          type: string
        description:
          type: string
        settings:
          $ref: '#/components/schemas/PasswordPolicySettings'
        applies_to:
          type: array
          items:
            type: string
          description: DNs of users and groups.
    PasswordPolicyList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PasswordPolicy'
    CreatePasswordPolicyRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - settings
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        settings:
          $ref: '#/components/schemas/PasswordPolicySettings'
        apply_to:
          type: array
          maxItems: 500
          items:
            type: string
            maxLength: 2048
    UpdatePasswordPolicyRequest:
      type: object
      additionalProperties: false
      properties:
        settings:
          $ref: '#/components/schemas/PasswordPolicySettings'
        apply_to:
          type: array
          maxItems: 500
          items:
            type: string
            maxLength: 2048
        unapply:
          type: array
          maxItems: 500
          items:
            type: string
            maxLength: 2048
    GPO:
      type: object
      required:
        - id
        - display_name
        - status
        - description
        - owner
        - wmi_filter
        - user_version
        - computer_version
        - builtin
        - link_count
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        status:
          type: string
          enum:
            - AllSettingsEnabled
            - UserSettingsDisabled
            - ComputerSettingsDisabled
            - AllSettingsDisabled
        description:
          type: string
        owner:
          type: string
        wmi_filter:
          type: string
        created:
          type: string
          format: date-time
          nullable: true
        modified:
          type: string
          format: date-time
          nullable: true
        user_version:
          type: integer
        computer_version:
          type: integer
        builtin:
          type: boolean
          description: Default Domain (Controllers) Policy; Vertex never changes them.
        link_count:
          type: integer
    GPOList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/GPO'
    GPOLinkTarget:
      type: object
      required:
        - ou_id
        - dn
        - name
        - enabled
        - enforced
        - order
        - in_scope
      properties:
        ou_id:
          type: string
          format: uuid
        dn:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        enforced:
          type: boolean
        order:
          type: integer
        in_scope:
          type: boolean
    GPODetail:
      allOf:
        - $ref: '#/components/schemas/GPO'
        - type: object
          required:
            - links
          properties:
            links:
              type: array
              items:
                $ref: '#/components/schemas/GPOLinkTarget'
    GPOReport:
      type: object
      required:
        - gpo_id
        - xml
        - complete
        - fetched_at
      properties:
        gpo_id:
          type: string
          format: uuid
        xml:
          type: string
          description: Get-GPOReport -ReportType Xml.
        complete:
          type: boolean
        fetched_at:
          type: string
          format: date-time
    CreateGPORequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        comment:
          type: string
          maxLength: 2048
        link_to:
          type: string
          maxLength: 2048
          description: An OU DN to link the new GPO to.
    UpdateGPORequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        status:
          type: string
          enum:
            - AllSettingsEnabled
            - UserSettingsDisabled
            - ComputerSettingsDisabled
            - AllSettingsDisabled
        comment:
          type: string
          maxLength: 2048
    GPOLinkRequest:
      type: object
      additionalProperties: false
      required:
        - target_dn
        - action
      properties:
        target_dn:
          type: string
          minLength: 1
          maxLength: 2048
        action:
          type: string
          enum:
            - link
            - unlink
            - set
        enabled:
          type: boolean
        enforced:
          type: boolean
        order:
          type: integer
          minimum: 1
          maximum: 1000
    RegistryValue:
      type: object
      additionalProperties: false
      required:
        - scope
        - key
        - value_name
      properties:
        scope:
          type: string
          enum:
            - computer
            - user
        key:
          type: string
          minLength: 1
          maxLength: 1024
          description: >-
            Relative to HKLM/HKCU, e.g.
            Software\Policies\Microsoft\Windows\Personalization
        value_name:
          type: string
          maxLength: 255
        type:
          type: string
          enum:
            - String
            - ExpandString
            - DWord
            - QWord
            - MultiString
            - Binary
        value:
          type: string
          maxLength: 16384
          description: Decimal for DWord/QWord
          hex for Binary: null
          one line per value for MultiString.: null
    GPORegistryRequest:
      type: object
      additionalProperties: false
      properties:
        set:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/RegistryValue'
        remove:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/RegistryValue'
    GPOPermissionRequest:
      type: object
      additionalProperties: false
      required:
        - trustee
        - trustee_type
        - level
      properties:
        trustee:
          type: string
          minLength: 1
          maxLength: 300
        trustee_type:
          type: string
          enum:
            - User
            - Group
            - Computer
        level:
          type: string
          enum:
            - None
            - GpoRead
            - GpoApply
            - GpoEdit
            - GpoEditDeleteModifySecurity
        replace:
          type: boolean
          default: false
    ImportMode:
      type: string
      enum:
        - create
        - update
        - upsert
    ImportOptions:
      type: object
      additionalProperties: false
      properties:
        default_ou:
          type: string
          maxLength: 2048
          description: For rows without an ou.
        upn_suffix:
          type: string
          maxLength: 253
          description: Builds userPrincipalName for rows without one.
        enabled:
          type: boolean
          description: >-
            For rows without an enabled column (default true when a password is
            given).
        must_change_password:
          type: boolean
          description: For rows without the column (default true).
    CreateImportRequest:
      type: object
      additionalProperties: false
      required:
        - csv
        - mode
      properties:
        filename:
          type: string
          maxLength: 255
        csv:
          type: string
          minLength: 1
          maxLength: 5242880
        mode:
          $ref: '#/components/schemas/ImportMode'
        options:
          $ref: '#/components/schemas/ImportOptions'
    ImportStatus:
      type: string
      enum:
        - validated
        - running
        - completed
        - failed
        - cancelled
        - expired
    BulkImport:
      type: object
      required:
        - id
        - filename
        - mode
        - status
        - options
        - total
        - invalid
        - to_create
        - to_update
        - created
        - updated
        - unchanged
        - failed
        - created_at
        - expires_at
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
        mode:
          $ref: '#/components/schemas/ImportMode'
        status:
          $ref: '#/components/schemas/ImportStatus'
        options:
          $ref: '#/components/schemas/ImportOptions'
        total:
          type: integer
        invalid:
          type: integer
        to_create:
          type: integer
        to_update:
          type: integer
        created:
          type: integer
        updated:
          type: integer
        unchanged:
          type: integer
        failed:
          type: integer
        created_by:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        committed_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          description: An uncommitted import is discarded then.
    BulkImportList:
      type: object
      required:
        - items
        - page
        - page_size
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/BulkImport'
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
    ImportRowAction:
      type: string
      enum:
        - create
        - update
        - invalid
    ImportRowStatus:
      type: string
      enum:
        - pending
        - skipped
        - created
        - updated
        - unchanged
        - failed
    ImportRow:
      type: object
      required:
        - row_no
        - sam_account_name
        - data
        - has_password
        - action
        - problems
        - status
        - error_code
        - error
      properties:
        row_no:
          type: integer
          description: Line number in the file (the header is 1).
        sam_account_name:
          type: string
        data:
          type: object
          additionalProperties: true
          description: The parsed row (without the password).
        has_password:
          type: boolean
        action:
          $ref: '#/components/schemas/ImportRowAction'
        problems:
          type: array
          items:
            type: string
        status:
          $ref: '#/components/schemas/ImportRowStatus'
        error_code:
          type: string
        error:
          type: string
        object_id:
          type: string
          format: uuid
          nullable: true
    ImportRowList:
      type: object
      required:
        - items
        - page
        - page_size
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ImportRow'
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer
    StepUpRequest:
      type: object
      additionalProperties: false
      required:
        - step_up_token
      properties:
        step_up_token:
          type: string
          minLength: 1
          maxLength: 4096
    OperationStatus:
      type: string
      enum:
        - pending
        - queued
        - running
        - succeeded
        - failed
        - cancelled
        - timeout
    OperationClass:
      type: string
      enum:
        - read
        - user
        - group
        - ou
        - gpo
        - pso
    Operation:
      type: object
      required:
        - id
        - op
        - class
        - is_delete
        - target_kind
        - target_id
        - target_dn
        - summary
        - status
        - progress_message
        - error_code
        - error
        - created_by_email
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        op:
          type: string
          description: e.g. user.create, object.update, gpo.link, bulk.users
        class:
          $ref: '#/components/schemas/OperationClass'
        is_delete:
          type: boolean
        target_kind:
          type: string
        target_id:
          type: string
        target_dn:
          type: string
        summary:
          type: string
        params:
          type: object
          additionalProperties: true
          description: What was requested (never passwords).
        status:
          $ref: '#/components/schemas/OperationStatus'
        progress_pct:
          type: integer
          nullable: true
        progress_message:
          type: string
        error_code:
          type: string
          description: >-
            e.g. guard_pending, out_of_scope, protected, access_denied,
            password_policy, connector_offline
        error:
          type: string
        result:
          type: object
          nullable: true
          additionalProperties: true
        created_by:
          type: string
          format: uuid
          nullable: true
        created_by_email:
          type: string
        bulk_import_id:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
          nullable: true
    OperationBatch:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
    OperationList:
      type: object
      required:
        - items
        - page
        - page_size
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Operation'
        page:
          type: integer
        page_size:
          type: integer
        total:
          type: integer