openapi: 3.0.3
info:
  title: TenantPilot - Policy Settings Ingestion API
  description: |
    API for ingesting Intune policy settings from external sources (n8n workflows).
    
    **Security**: All endpoints require `X-API-SECRET` header authentication.
  version: 1.0.0
  contact:
    name: TenantPilot

servers:
  - url: /api
    description: API base path

security:
  - ApiSecretAuth: []

paths:
  /policy-settings:
    post:
      summary: Bulk upsert policy settings
      description: |
        Upserts multiple policy settings for a tenant. 
        Settings are identified by the combination of (tenantId, graphPolicyId, settingName).
        Existing settings are updated, new settings are inserted.
      operationId: upsertPolicySettings
      tags:
        - Policy Settings
      security:
        - ApiSecretAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkPolicySettingsRequest'
            example:
              settings:
                - tenantId: "12345678-1234-1234-1234-123456789abc"
                  policyName: "Windows 11 Baseline"
                  policyType: "deviceConfiguration"
                  settingName: "BitLocker.RequireEncryption"
                  settingValue: "true"
                  graphPolicyId: "policy-guid-from-graph"
                - tenantId: "12345678-1234-1234-1234-123456789abc"
                  policyName: "Windows 11 Baseline"
                  policyType: "deviceConfiguration"
                  settingName: "Defender.EnableRealTimeProtection"
                  settingValue: "true"
                  graphPolicyId: "policy-guid-from-graph"
      responses:
        '200':
          description: Settings upserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpsertResponse'
              example:
                success: true
                upsertedCount: 2
                message: "2 settings upserted successfully"
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Validation failed"
                details:
                  - field: "settings[0].policyType"
                    message: "Invalid policy type"
        '401':
          description: Unauthorized - Missing or invalid API secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: "Unauthorized"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      summary: Delete all policy settings for a tenant
      description: |
        Deletes all policy settings for a specific tenant.
        Use with caution - this is a destructive operation.
      operationId: deleteTenantPolicySettings
      tags:
        - Policy Settings
      security:
        - ApiSecretAuth: []
      parameters:
        - name: tenantId
          in: query
          required: true
          description: Azure AD tenant ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Settings deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
              example:
                success: true
                deletedCount: 150
                message: "150 settings deleted for tenant"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiSecretAuth:
      type: apiKey
      in: header
      name: X-API-SECRET
      description: |
        Secret key for API authentication.
        Set via `POLICY_API_SECRET` environment variable.
        
        **Required for all ingestion operations.**

  schemas:
    PolicySettingInput:
      type: object
      required:
        - tenantId
        - policyName
        - policyType
        - settingName
        - settingValue
        - graphPolicyId
      properties:
        tenantId:
          type: string
          format: uuid
          description: Azure AD tenant ID
        policyName:
          type: string
          minLength: 1
          description: Display name of the Intune policy
        policyType:
          type: string
          enum:
            - deviceConfiguration
            - compliancePolicy
            - windowsUpdateForBusiness
            - endpointSecurity
            - appConfiguration
            - enrollmentRestriction
            - conditionalAccess
          description: Type/category of the policy
        settingName:
          type: string
          minLength: 1
          description: Name of the individual setting
        settingValue:
          type: string
          description: Value of the setting (JSON-stringified if complex)
        graphPolicyId:
          type: string
          minLength: 1
          description: Microsoft Graph API policy ID

    BulkPolicySettingsRequest:
      type: object
      required:
        - settings
      properties:
        settings:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: '#/components/schemas/PolicySettingInput'
          description: Array of policy settings to upsert

    BulkUpsertResponse:
      type: object
      properties:
        success:
          type: boolean
        upsertedCount:
          type: integer
          description: Number of settings upserted
        message:
          type: string

    DeleteResponse:
      type: object
      properties:
        success:
          type: boolean
        deletedCount:
          type: integer
          description: Number of settings deleted
        message:
          type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
          description: Detailed validation errors (optional)