openapi: 3.0.0
info:
  version: 2.3.2
  title: eIM Info API
  description: |

    #### Copyright
    © Aeris Communications, Inc. 2026. All rights reserved. No part of this document may be reproduced in any form without the written permission of the copyright owner.

    #### Disclaimer

    The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing.
    Aeris shall have no liability for any error or damage of any kind resulting from the use of this document.

    #### Trademark List

    All trademarks mentioned herein are the property of their respective owners.
    These are shown in the document Trademark Information.

    # Introduction

    This document describes the IoT Accelerator eIM Info API that provides read access to eIM information resources.
    The eIM Info API is based on the Representational State Transfer (REST) interface.
    From this point on, the eIM Info API is referred to as API in this document.

    ## Scope

    This document covers the following topics:

    - An overview of the API

    - A detailed description of all operations offered by the API

    ## Prerequisites
    In this document, it is assumed that the user is familiar with the following:

    - Java Script Object Notation (JSON)

    - Basic understanding of REST web services

    - The [OpenAPI Initiative](https://www.openapis.org/) for the standardized format used in this document.

    ## Related Information
    The definition and explanation of acronyms and terminology and typographic conventions can be found in the following documents:

    - IoTA Glossary of Terms and Acronyms

    - Typographic Conventions

    # General API Guidelines

    ## Compatibility

    API audience must be prepared for compatible API extensions:

    - Be tolerant with unknown fields in the payload (see also Fowler’s "TolerantReader" post), i.e. ignore new fields but do not eliminate them from payload if needed for subsequent PUT requests.
    - Be prepared that "x-extensible-enum" return parameter may deliver new values. Either be agnostic or provide default behavior for unknown values.
    - Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions.
    - Follow the redirect when the server returns HTTP status 301 Moved Permanently.

    ## Security

    This section describes the security measures in the API. Security measures include authentication, authorization, and encryption.

    ### Authentication and Authorization

    The API uses OAuth2 and OpenID Connect (OIDC) for authentication and authorization.

    All API endpoints require authentication, which is performed by passing a token in the Authorization header in each request, preceded by the word Bearer and a space. See the following example:
    ```
    curl -i -X GET "http://<baseURL>/iot/api/x-entities" -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN_GOES_HERE>"
    ```
    To fetch the token using e.g. curl, submit the following:
    ```
    curl -X POST "https://<baseURL>/iot/api/auth/token" -H "Accept: application/vnd.dcp-v1+json" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&client_id=<client_id>&username=<username>&password=<password>"
    ```

    ### Encryption

    All API requests are encrypted using the HTTPS protocol to grant secure data transfer.

    ## Deprecation

    API deprecation will be reflected in the OpenAPI definition. If a method on a path, a whole path or even a whole API endpoint (multiple paths) should be deprecated, they will be marked as deprecated.
    During deprecation phase, a Deprecation header and a Sunset header fields will be added in the response.

    Example:
    ```
    Deprecation: Tue, 31 Dec 2024 23:59:59 GMT
    Sunset: Wed, 31 Dec 2025 23:59:59 GMT
    ```

    API audience should not start using a deprecated API.

    API audience is encouraged to monitor for Deprecation and Sunset header.

  x-audience: external-public
  x-api-id: 8f546a89-2247-4254-8c9e-0b2900a5f491
servers:
  - url: 'https://iot-api.aeris.com/iot/api'
    description: API server
tags:
  - name: 'EimInfo'
    description: eIM information
paths:
  /eim-info/list:
    get:
      tags:
        - 'EimInfo'
      summary: List eIM infos
      operationId: listEimInfos
      description: Retrieves eIM information records.
      parameters:
        - $ref: '#/components/parameters/Header-Content-Type'
        - $ref: '#/components/parameters/Header-Accept-Version'
        - name: Accept
          in: header
          description: Accept content-type and schemas by the client
          content:
            application/json:
              schema:
                type: string
      responses:
        '200':
          description: OK
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EimInfoList001'
              examples:
                "List eIM infos response":
                  $ref: '#/components/examples/EimInfoListExample'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - OAuth2:
            - 'cnx_eim_read'

  /eim-info/{eimInfoEntityId}:
    get:
      tags:
        - 'EimInfo'
      summary: Get eIM info
      operationId: getEimInfo
      description: Retrieves eIM information by entity id.
      parameters:
        - $ref: '#/components/parameters/Header-Content-Type'
        - $ref: '#/components/parameters/Header-Accept-Version'
        - name: Accept
          in: header
          description: Accept content-type and schemas by the client
          content:
            application/json:
              schema:
                type: string
        - name: eimInfoEntityId
          in: path
          description: eIM entity id.
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: OK
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EimInfo001'
              examples:
                "Get eIM info response":
                  $ref: '#/components/examples/EimInfoExample'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - OAuth2:
            - 'cnx_eim_read'

  /eim-info/{euiccId}/eims:
    get:
      tags:
        - 'EimInfo'
      summary: Get eIMs mapped to an eUICC
      operationId: getEuiccEims
      description: Retrieves eIMs mapped to an eUICC.
      parameters:
        - $ref: '#/components/parameters/Header-Content-Type'
        - $ref: '#/components/parameters/Header-Accept-Version'
        - name: Accept
          in: header
          description: Accept content-type and schemas by the client
          content:
            application/json:
              schema:
                type: string
        - name: euiccId
          in: path
          description: hexadecimal digit eUICC ID
          required: true
          schema:
            type: string
            pattern: '(^[0-9A-F]{32})|([0-9A-Fa-f]{20,30}$)'
      responses:
        '200':
          description: Mapped eIMs found
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EuiccEim001'
              examples:
                "Get euicc eims response":
                  $ref: '#/components/examples/EuiccEimListExample'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
        default:
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - OAuth2:
            - 'cnx_eim_read'

components:
  schemas:
    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: 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
          exclusiveMaximum: true
          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.
          example: 'https://api.documentation.url/request-id'

    EimInfoList001:
      type: array
      items:
        $ref: '#/components/schemas/EimInfo001'

    EimInfo001:
      type: object
      required:
        - entityId
        - eimId
        - eimName
        - eimIdType
        - eimFqdn
        - supportedProtocols
        - indirectProfileDownload
      properties:
        entityId:
          type: string
        eimId:
          type: string
          maxLength: 128
        eimName:
          type: string
          maxLength: 256
        eimIdType:
          type: string
        eimFqdn:
          type: string
          maxLength: 255
        supportedProtocols:
          type: array
          items:
            $ref: '#/components/schemas/SupportedProtocol001'
        indirectProfileDownload:
          type: boolean

    EuiccEim001:
      type: object
      properties:
        eim_id:
          type: string
        eim_fqdn:
          type: string
        eim_id_type:
          type: string
        indirect_profile_download:
          type: boolean

    SupportedProtocol001:
      type: string
      enum:
        - EIM_RETRIEVE_HTTPS
        - EIM_RETRIEVE_COAPS
        - EIM_INJECT_HTTPS
        - EIM_INJECT_COAPS
        - EIM_PROPRIETARY

  responses:
    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'
    '204':
      description: No Content
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'
    '400':
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: "https://your.api.documentation.url/bad-request"
            title: "Bad Request"
            status: 400
            detail: "The request could not be understood by the server due to malformed syntax"
            instance: "https://api.documentation.url/request-id"
    '401':
      description: Unauthorized
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: "https://your.api.documentation.url/unauthorized"
            title: "Unauthorized"
            status: 401
            detail: "Authentication credentials were missing or incorrect"
            instance: "https://api.documentation.url/request-id"
    '403':
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: "https://your.api.documentation.url/forbidden"
            title: "Forbidden"
            status: 403
            detail: "The server understood the request but refuses to authorize it"
            instance: "https://api.documentation.url/request-id"
    '404':
      description: Not Found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: "https://your.api.documentation.url/not-found"
            title: "Not Found"
            status: 404
            detail: "The requested resource could not be found"
            instance: "https://api.documentation.url/request-id"
    '405':
      description: Method Not Allowed
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: "https://your.api.documentation.url/method-not-allowed"
            title: "Method Not Allowed"
            status: 405
            detail: "The request method is not supported for this resource"
            instance: "https://api.documentation.url/request-id"
    '429':
      description: Too Many Requests
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: "https://your.api.documentation.url/too-many-requests"
            title: "Too Many Requests"
            status: 429
            detail: "The user has sent too many requests in a given amount of time"
            instance: "https://api.documentation.url/request-id"
    '500':
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: "https://your.api.documentation.url/internal-server-error"
            title: "Internal Server Error"
            status: 500
            detail: "The server encountered an unexpected condition that prevented it from fulfilling the request"
            instance: "https://api.documentation.url/request-id"

  examples:
    EimInfoExample:
      value:
        entityId: "EIM000000000006"
        eimId: "1.3.6.1.4.1.31746.1.800.102.1.3.2.12"
        eimName: "AerisEIMFQDN2"
        eimIdType: "EIM_ID_TYPE_FQDN"
        eimFqdn: "eim.iot.fqdn.aeris.com"
        supportedProtocols:
          - "EIM_RETRIEVE_HTTPS"
          - "EIM_RETRIEVE_COAPS"
          - "EIM_INJECT_HTTPS"
          - "EIM_INJECT_COAPS"
          - "EIM_PROPRIETARY"
        indirectProfileDownload: false
    EimInfoListExample:
      value:
        - entityId: "EIM000000000006"
          eimId: "1.3.6.1.4.1.31746.1.800.102.1.3.2.12"
          eimName: "AerisEIMFQDN2"
          eimIdType: "EIM_ID_TYPE_FQDN"
          eimFqdn: "eim.iot.fqdn.aeris.com"
          supportedProtocols:
            - "EIM_RETRIEVE_HTTPS"
            - "EIM_RETRIEVE_COAPS"
            - "EIM_INJECT_HTTPS"
            - "EIM_INJECT_COAPS"
            - "EIM_PROPRIETARY"
          indirectProfileDownload: false

    EuiccEimListExample:
      value:
        - eim_id: "1.2.3.4"
          eim_fqdn: "eim.enterprise-x.example"
          eim_id_type: "EIM_ID_TYPE_OID"
          indirect_profile_download: true

  parameters:
    Header-Accept:
      name: Accept
      in: header
      description: Accept content-type by the client
      schema:
        type: string
    Header-Accept-Version:
      name: Accept-Version
      in: header
      description: Accept version of the response
      schema:
        type: string
    Header-Content-Type:
      name: Content-Type
      in: header
      description: Content-Type
      schema:
        type: string

  headers:
    Content-Type:
      description: Handle Content-Type
      schema:
        type: string
    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
    X-RateLimit-Remaining-Second:
      description: The number of requests remaining in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining-Minute:
      description: The number of requests remaining in a minute.
      schema:
        type: integer
        format: int32

  securitySchemes:
    OAuth2:
      type: oauth2
      description: The resources in the API are protected using the OAuth 2.0 protocol
      flows:
        clientCredentials:
          tokenUrl: https://iot-api.aeris.com/iot/api/auth/token
          scopes:
            cnx_eim_read: Grant client read access to eIM info resources