openapi: 3.2.0
info:
  version: 3.9.3
  title: Enterprise Management Enterprise Group API
  description: '#### Copyright

    © Aeris Communications, Inc.'
  contact:
    name: Aeris IoT SaaS
    url: https://support.aeris.net/hc/en-us
  x-audience: external-partner
  x-api-id: 30a38694-63dc-4fbd-8bed-5b8ffdfe0e19
servers:
- url: https://iot-api.aeris.com/iot/api/ecm
  description: Main API server
tags:
- name: EnterpriseGroup
paths:
  /enterprises/enterprise_groups/{enterprise_group_id}:
    get:
      tags:
      - EnterpriseGroup
      summary: Get details of an enterprise group
      operationId: getEnterpriseGroupDetails
      parameters:
      - $ref: '#/components/parameters/enterpriseGroupIdParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterpriseGroupDetail'
            application/json;version=2.0.0:
              schema:
                $ref: '#/components/schemas/EnterpriseGroupDetail'
          allOf:
          - $ref: '#/components/responses/RateLimitedResponse'
        '429':
          $ref: '#/components/responses/429'
        default:
          description: The standard http error codes will be given. Usually 400,403,401,404 or 500.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth2:
        - css_view_enterprise_groups
    put:
      tags:
      - EnterpriseGroup
      summary: Update an existing enterprise group
      description: Updates an existing enterprise group.
      operationId: updateEnterpriseGroup
      parameters:
      - $ref: '#/components/parameters/enterpriseGroupIdParam'
      - name: If-Match
        in: header
        description: The RFC 7232 If-Match header field in a request requires the server to only operate on the resource that matches the provided entity-tag. This allows clients express a precondition that prevent the method from being applied if there have been any changes to the resource. See the response headers of GET /enterprises/enterprise_id for details about the entity-tag.
        schema:
          type: string
          example: '11'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnterpriseGroupUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterpriseGroupDetail'
            application/json;version=2.0.0:
              schema:
                $ref: '#/components/schemas/EnterpriseGroupDetail'
          allOf:
          - $ref: '#/components/responses/RateLimitedResponse'
        '412':
          description: Precondition Failed (entity-tag is missing or does not match the latest version)
        '429':
          $ref: '#/components/responses/429'
        default:
          description: The standard http error codes will be given. 4XX for client errors and 5XX for server errors.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth2:
        - css_manage_enterprise_hierarchy
        - css_manage_enterprise_groups
components:
  headers:
    X-RateLimit-Remaining-Minute:
      description: The number of requests remaining in a minute.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Second:
      description: The maximum number of requests allowed in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Minute:
      description: The maximum number of requests allowed in a minute.
      schema:
        type: integer
        format: int32
    Content-Type:
      description: Handle Content-Type
      schema:
        type: string
    X-RateLimit-Remaining-Second:
      description: The number of requests remaining in a second.
      schema:
        type: integer
        format: int32
  parameters:
    enterpriseGroupIdParam:
      in: path
      name: enterprise_group_id
      description: The id of the requested enterprise group.
      required: true
      schema:
        type: string
        minLength: 3
        maxLength: 255
        example: 1.2.3.44
  schemas:
    Status:
      type: string
      description: Status of the entity
      x-extensible-enum:
      - DRAFT
      - READY
      - INVALID
      - SUBMITTED
      - OBSOLETE
      example: READY
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: 'An absolute URI that identifies the problem type. When dereferenced,it SHOULD provide

            human-readable documentation for the problem type (e.g., using HTML).

            '
          default: about:blank
          example: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable for engineers (usually not suited

            for non technical stakeholders and not localized.

            '
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          example: 503
          exclusiveMaximum: 600
        detail:
          type: string
          description: A human readable explanation specific to this occurrence of the problem.
          example: Connection to database timed out.
        instance:
          type: string
          description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          example: https://api.documentation.url/request-id
    ProblemGeneric:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: 'An absolute URI that identifies the problem type. When dereferenced,

            it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          default: about:blank
          example: https://your.api.documentation.url
        title:
          type: string
          description: 'A short, summary of the problem type. Written in english and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized);

            '
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          maximum: 600
          example: 503
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Connection to database timed out
        instance:
          type: string
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
          default: about:blank
          example: /iot/api/problems/123e4567-e89b-12d3-a456-426614174000
    EnterpriseGroupUpdate:
      allOf:
      - $ref: '#/components/schemas/EnterpriseGroupWrite'
    EnterpriseGroupWrite:
      type: object
      properties:
        companies:
          type: array
          description: 'dcpIds of companies to be in the enterprise group.

            '
          items:
            type: integer
            format: int64
      required:
      - companies
    EnterpriseGroupDetail:
      allOf:
      - $ref: '#/components/schemas/EnterpriseGroupRead'
    EnterpriseRead:
      type: object
      properties:
        id:
          type: string
          description: Enterprise ID.
          minLength: 3
          maxLength: 255
          example: 1.2.3.44
        customer_number:
          deprecated: true
          type: string
          description: Legacy identifier for the enterprise. API clients should start transitioning to use id instead as the customer_number will be removed. Date of removal is not yet known; notice will be given at least 6 months before.
          minLength: 8
          maxLength: 8
          example: '02000044'
        parent_number:
          deprecated: true
          type: string
          description: Legacy identifier for the enterprise's parent. API clients should start transitioning to use id instead as the parent_number will be removed, and id contains the parent ID. Date of removal is not yet known; notice will be given at least 6 months before.
          maxLength: 255
          example: '02000001'
        parent_id:
          type: string
          description: ID of the parent organization
          maxLength: 255
          example: 1.2.3
        name:
          type: string
          description: Enterprise name.
          minLength: 1
          maxLength: 80
          example: MyCompany
        description:
          type:
          - string
          - 'null'
          description: Enterprise description.
          maxLength: 255
          example: MyCompany description
        enterprise_type:
          description: Type of the enterprise.
          type: string
          x-extensible-enum:
          - ENTERPRISE
          - ADVANCED_RESELLER
          - CONTROLLED_RESELLER
          default: ENTERPRISE
          example: ENTERPRISE
        created_at:
          type: string
          description: The time when the enterprise was created (ISO 8601 UTC)
          example: '2019-06-28T00:00:00.000Z'
        status:
          $ref: '#/components/schemas/Status'
        provisioning_status:
          $ref: '#/components/schemas/ProvisioningStatus'
        tags:
          type: array
          description: A list of API consumer defined text strings that can be used to further describe an enterprise.
          maxItems: 10
          items:
            type: string
          example:
          - business:finance
          - market:europe
        template_sp_id:
          type: array
          description: A list of template subscription package id are used for an enterprise.
          items:
            type: integer
            format: int64
          example:
          - '1231'
          - '1232'
      required:
      - id
      - parent_id
      - name
      - created_at
      - status
    EnterpriseGroupRead:
      type: object
      properties:
        group_id:
          type: string
          description: group ID of the enterprise group.
          minLength: 1
          maxLength: 255
          example: 0.1
        parent_group_id:
          type: string
          description: group ID of the parent.
          minLength: 1
          maxLength: 255
          example: 0.1
        enterprise_group_type:
          description: ADVANCED_RESELLER, CONTROLLED_RESELLER or ENTERPRISE
          type: string
          x-extensible-enum:
          - ADVANCED_RESELLER
          - CONTROLLED_RESELLER
          - ENTERPRISE
          example: ENTERPRISE
        lead_organization:
          type: string
          description: ID of the lead organization.
          minLength: 1
          maxLength: 255
          example: 1.2.3.44
        companies:
          type: array
          description: 'The list of companies within the enterprise group.

            '
          items:
            $ref: '#/components/schemas/EnterpriseRead'
    ProvisioningStatus:
      type: string
      description: Provisioning status of the entity
      x-extensible-enum:
      - NONE
      - PENDING
      - STARTED
      - SUCCESS
      - FAILURE
      example: SUCCESS
  responses:
    '429':
      description: Too Many Requests
      allOf:
      - $ref: '#/components/responses/RateLimitedResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemGeneric'
          example:
            type: about:blank
            title: Too Many Requests
            status: 429
            detail: Too Many Requests. Please refer response RateLimit-* headers before send requests.
            instance: about:blank
    RateLimitedResponse:
      headers:
        X-RateLimit-Limit-Second:
          $ref: '#/components/headers/X-RateLimit-Limit-Second'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/X-RateLimit-Limit-Minute'
        X-RateLimit-Remaining-Second:
          $ref: '#/components/headers/X-RateLimit-Remaining-Second'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/X-RateLimit-Remaining-Minute'
        Content-Type:
          $ref: '#/components/headers/Content-Type'
  securitySchemes:
    oauth2:
      type: oauth2
      description: The Enterprise API uses OAuth2 and OIDC for authentication and authorization.
      flows:
        password:
          tokenUrl: https://iot-api.aeris.com/iot/api/auth/token
          scopes:
            css_manage_enterprise_hierarchy: Grants access to read, create and update enterprise and subscription package information.
            css_view_resources: Grants access to read resource information.