openapi: 3.0.3
info:
  title: TenantPilot - Intune Write Gate (Provider Access Hardening v1)
  version: 1.0.0
  description: |
    Conceptual contract for server-side gating of Intune write operations.

    Note: In the current application these actions are initiated via Filament/Livewire
    surfaces (not a public JSON API). This contract documents the expected request/response
    semantics, stable reason codes, and outcome metadata for the gate.
servers:
  - url: https://tenantpilot.local
paths:
  /tenants/{tenantId}/operations/restore/execute:
    post:
      summary: Start restore execution (Intune write)
      parameters:
        - name: tenantId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [restoreRunId]
              properties:
                restoreRunId:
                  type: integer
                dryRun:
                  type: boolean
                  default: false
      responses:
        "202":
          description: Accepted (OperationRun created/enqueued)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OperationStarted"
        "422":
          description: Precondition failed (RBAC hardening gate blocked)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GateBlocked"
  /tenants/{tenantId}/operations/assignments/restore:
    post:
      summary: Start assignments restore (Intune write)
      parameters:
        - name: tenantId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [restoreRunId, policyType, policyId]
              properties:
                restoreRunId:
                  type: integer
                policyType:
                  type: string
                policyId:
                  type: string
      responses:
        "202":
          description: Accepted (OperationRun created/enqueued)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OperationStarted"
        "422":
          description: Precondition failed (RBAC hardening gate blocked)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GateBlocked"
  /tenants/{tenantId}/operations/intune-rbac/refresh:
    post:
      summary: Start async RBAC health check refresh
      parameters:
        - name: tenantId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "202":
          description: Accepted (OperationRun created/enqueued)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OperationStarted"
components:
  schemas:
    OperationStarted:
      type: object
      required: [operationRunId, type]
      properties:
        operationRunId:
          type: integer
        type:
          type: string
        status:
          type: string
          enum: [queued, running]
    GateBlocked:
      type: object
      required: [reason_code, message]
      properties:
        reason_code:
          type: string
          enum:
            - intune_rbac.not_configured
            - intune_rbac.unhealthy
            - intune_rbac.stale
        message:
          type: string
        cta:
          type: object
          nullable: true
          properties:
            label:
              type: string
            url:
              type: string