openapi: 3.2.0
info:
  version: 0.7.0
  title: Aeris IoT Watchtower™ Enforcement Rules API
  description: '## Introduction


    The Aeris IoT Watchtower™ API provides access to resources such as real-time events, aggregated events, risk assessment reports, and device group operations.'
  termsOfService: https://www.aeris.com/services-terms-of-use/
  contact:
    email: support@aeris.net
    url: https://www.aeris.com/support/
  license:
    name: Aeris License
    url: https://www.aeris.com/services-terms-of-use/
  x-audience: external-public
servers:
- url: https://watchtower-api-prd.aeriscloud.com
security:
- oAuth2ClientCredentials: []
tags:
- name: Enforcement Rules
  description: Endpoints for Enforcement Rules
paths:
  /watchtower/v1/enforcement-rules:
    post:
      summary: Create an enforcement rule
      operationId: createEnforcementRule
      tags:
      - Enforcement Rules
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnforcementRuleCreateRequest'
      responses:
        '201':
          description: Enforcement rule created successfully
          content:
            application/json:
              schema:
                type: integer
                format: int64
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/enforcement-rules/search:
    post:
      summary: Search enforcement rules
      operationId: searchEnforcementRules
      tags:
      - Enforcement Rules
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/startTime'
      - $ref: '#/components/parameters/endTime'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/sort'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnforcementRulesQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedEnforcementRules'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/enforcement-rules/{enforcementRuleId}:
    get:
      summary: Get an enforcement rule
      operationId: getEnforcementRule
      tags:
      - Enforcement Rules
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/enforcementRuleId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnforcementRule'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    put:
      summary: Update an existing enforcement rule
      operationId: updateEnforcementRule
      tags:
      - Enforcement Rules
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/enforcementRuleId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnforcementRuleUpdateRequest'
      responses:
        '204':
          description: No content, the resource was successfully updated.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    delete:
      summary: Delete an enforcement rule
      operationId: deleteEnforcementRule
      tags:
      - Enforcement Rules
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/enforcementRuleId'
      responses:
        '204':
          description: No content, the resource was successfully deleted.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/enforcement-rules/{enforcementRuleId}/activate:
    post:
      summary: Activate an enforcement rule
      operationId: activateEnforcementRule
      tags:
      - Enforcement Rules
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/enforcementRuleId'
      responses:
        '204':
          description: No content, the resource was successfully updated.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /watchtower/v1/enforcement-rules/{enforcementRuleId}/deactivate:
    post:
      summary: Deactivate an enforcement rule
      operationId: deactivateEnforcementRule
      tags:
      - Enforcement Rules
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/enforcementRuleId'
      responses:
        '204':
          description: No content, the resource was successfully updated.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    startTime:
      name: startTime
      in: query
      required: true
      description: The start timestamp. (inclusive)
      example: '2021-07-01T06:30:00Z'
      schema:
        $ref: '#/components/schemas/dateTime'
    endTime:
      name: endTime
      in: query
      required: true
      description: The end timestamp. (exclusive)
      example: '2021-07-05T06:30:00Z'
      schema:
        $ref: '#/components/schemas/dateTime'
    enforcementRuleId:
      name: enforcementRuleId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/enforcementRuleId'
    sort:
      name: sort
      in: query
      description: Use <b>sort=comma-separated-fields[:asc|desc]</b> to sort the result.
      example: deviceId,updateTime:desc
      schema:
        type: string
    accountId:
      name: X-Watchtower-Account-Id
      in: header
      description: Account Id
      required: true
      schema:
        $ref: '#/components/schemas/accountId'
      example: 1002000010
    offset:
      name: offset
      in: query
      description: The position in pagination. Specifies the starting row offset into the result set returned. For example, if the page size (limit) is 10, then to select the second page, pass the offset as 10 to retrieve items 11 to 20.<br><br> Search parameters must be consistent across pages.
      schema:
        $ref: '#/components/schemas/offset'
    authorization:
      name: Authorization
      in: header
      description: Bearer Token for authentication
      required: true
      schema:
        type: string
        pattern: ^Bearer [A-Za-z0-9-._~+/]+=*$
      example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...
    limit:
      name: limit
      in: query
      description: The number of items to retrieve per page (10000 max).
      schema:
        $ref: '#/components/schemas/limit'
  responses:
    '429':
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 429
            message: 'Rate Limit Exceeded (XX) for clientId: XXXXXX. Please retry after XXX seconds'
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '401':
      description: Not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            message: Unauthorized
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '403':
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 403
            message: Forbidden
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '400':
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            message: Bad Request
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 500
            message: Internal Server Error
            timestamp: 2025-06-01 13:28:03.967000
            path: /watchtower/v1/...
            traceId: c3db9d7a432317363c8bc5ddb5aadf4b
  schemas:
    EnforcementRuleCreateRequest:
      allOf:
      - $ref: '#/components/schemas/EnforcementRuleUpdateRequest'
      - type: object
        properties:
          enforce:
            type: boolean
            description: The enforcement rule should be enforced immediately after creation
            default: false
    applicationId:
      description: Application identifier
      type: integer
      format: int64
      example: 10407
    total:
      type: integer
      format: int64
      description: Total number of items available.
      example: 1
      minimum: 0
    offset:
      description: Position in pagination.
      type: integer
      format: int32
      default: 0
      minimum: 0
    limit:
      type: integer
      format: int32
      description: Number of items to retrieve (10000 max).
      minimum: 1
      maximum: 10000
      default: 20
    malwareProtectionLevel:
      type: string
      enum:
      - NONE
      - ESSENTIAL
      - AGGRESSIVE
      - COMPREHENSIVE
    accountId:
      description: Account Id.
      type: integer
      format: int32
      example: 10407
      minimum: 0
    EnforcementRuleUpdateRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        apn:
          type: string
        malwareProtectionLevel:
          $ref: '#/components/schemas/malwareProtectionLevel'
        applications:
          type: array
          items:
            $ref: '#/components/schemas/applicationId'
        protectionPolicies:
          type: array
          items:
            $ref: '#/components/schemas/protectionPolicyId'
        deviceGroupId:
          $ref: '#/components/schemas/deviceGroupId'
        forceReconnect:
          type: boolean
          description: Force devices reconnect - Kill switch
          default: false
        serviceConfigurations:
          type: array
          items:
            $ref: '#/components/schemas/ServiceConfigurationRequest'
        editMode:
          type: boolean
          description: When this flag is on, user could edit the policy related fields such as (Applications, Protection Policies, Malware Protection)  for ACTIVE/ENFORCED Enforcement Rules
          default: false
      required:
      - name
      - apn
      - malwareProtectionLevel
      - applications
      - protectionPolicies
    ServiceConfigurationRequest:
      type: object
      description: Service configuration input for create/update
      properties:
        serviceConfigurationId:
          type: integer
          format: int64
          description: Present only on update to identify an existing config. Null/absent for new.
        serviceConfigurationType:
          type: string
          description: Type of configuration e.g. SPLIT_BILLING, RATE_LIMIT
        name:
          type: string
        description:
          type: string
          maxLength: 500
          description: Optional details/description for this service configuration.
        config:
          type: object
          additionalProperties: true
          description: Type-specific configuration payload (generic JSON)
        applicationIds:
          type: array
          items:
            type: integer
            format: int64
          description: Application IDs this configuration is bound to
      required:
      - serviceConfigurationType
      - name
      - config
    ServiceConfiguration:
      type: object
      description: Service configuration in responses (includes server-generated fields)
      properties:
        serviceConfigurationId:
          type: integer
          format: int64
        serviceConfigurationType:
          type: string
        name:
          type: string
        description:
          type: string
        status:
          type: string
        config:
          type: object
          additionalProperties: true
        applicationIds:
          type: array
          items:
            type: integer
            format: int64
    enforcementRuleStatus:
      type: string
      enum:
      - ACTIVATED
      - DEACTIVATED
    protectionPolicyId:
      description: Protection Policy identifier
      type: integer
      format: int64
      example: 21091
    Error:
      type: object
      properties:
        code:
          type: integer
          description: HTTP code
          example: 500
        message:
          type: string
          description: Error message
          example: An error encountered in processing the request
        timestamp:
          type: string
          description: ISO DateTime
          example: '2025-06-02 09:01:53.678'
        path:
          type: string
          description: Endpoint path at which the error occured
          example: /watchtower/v1/events
        traceId:
          type: string
          description: Trace Id
          example: ed81f29f-ea9b-4099-aa00-f8ed40b7a567
    dateTime:
      description: ISO 8601 date time
      type: string
      format: date-time
      example: '2021-07-04T17:36:47Z'
    EnforcementRulesQueryRequest:
      properties:
        name:
          type: string
        description:
          type: string
        deviceGroups:
          type: array
          items:
            $ref: '#/components/schemas/deviceGroupId'
        apns:
          type: array
          items:
            type: string
        malwareProtectionLevel:
          type: array
          items:
            $ref: '#/components/schemas/malwareProtectionLevel'
        status:
          type: array
          items:
            $ref: '#/components/schemas/enforcementRuleStatus'
        applications:
          type: array
          items:
            $ref: '#/components/schemas/applicationId'
        protectionPolicies:
          type: array
          items:
            $ref: '#/components/schemas/protectionPolicyId'
    Pagination:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/total'
        offset:
          $ref: '#/components/schemas/offset'
        limit:
          $ref: '#/components/schemas/limit'
    deviceGroupId:
      description: Device Group ID.
      type: integer
      format: int64
    EnforcementRule:
      allOf:
      - $ref: '#/components/schemas/EnforcementRuleBase'
      - type: object
        properties:
          malwareProtectionLevel:
            $ref: '#/components/schemas/malwareProtectionLevel'
          applications:
            type: array
            items:
              $ref: '#/components/schemas/applicationId'
          protectionPolicies:
            type: array
            items:
              $ref: '#/components/schemas/protectionPolicyId'
          deviceGroupId:
            $ref: '#/components/schemas/deviceGroupId'
          forceReconnect:
            type: boolean
            description: Force devices reconnect - Kill switch
          serviceConfigurations:
            type: array
            items:
              $ref: '#/components/schemas/ServiceConfiguration'
          createdBy:
            type: string
          createdTime:
            type: string
            format: date-time
          updatedBy:
            type: string
          updatedTime:
            type: string
            format: date-time
    enforcementRuleId:
      description: Enforcement Rule identifier
      type: integer
      format: int64
      example: 5102010
    EnforcementRuleBase:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/enforcementRuleId'
        name:
          type: string
        status:
          type: string
        apn:
          type: string
    PagedEnforcementRules:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/EnforcementRule'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: This API uses OAuth 2 with the Client Credentials flow.
      flows:
        clientCredentials:
          tokenUrl: /watchtower/v1/auth/token
          scopes: {}