openapi: 3.0.3
info:
  title: EcoFlow IoT Open Platform Devices MQTT API
  description: The EcoFlow IoT Open Platform (developer.ecoflow.com) HTTP API lets registered developers read telemetry from and send control commands to EcoFlow devices (portable power stations, Delta/River series, PowerStream micro-inverters, smart plugs, Power Kits and more) that are bound to a user account. Access is authenticated with an accessKey / secretKey pair issued in the developer console; every request carries an HMAC-SHA256 `sign` header computed over the sorted request parameters plus `accessKey`, `nonce` and `timestamp`. Real-time streaming and command delivery is handled over MQTT (see the companion AsyncAPI); this HTTP surface covers device discovery, a snapshot of all device "quota" (property) values, targeted quota queries, device function commands, and retrieval of the MQTT connection certificate.
  version: '1.0'
  contact:
    name: EcoFlow Developer Platform
    url: https://developer.ecoflow.com
  x-source: Endpoint surface, headers and signing verified from EcoFlow developer portal (developer.ecoflow.com / developer-eu.ecoflow.com) and independent public-API client implementations (github.com/tolwi/hassio-ecoflow-cloud).
servers:
- url: https://api.ecoflow.com
  description: Global / US region
- url: https://api-e.ecoflow.com
  description: Europe region
security:
- accessKey: []
  nonce: []
  timestamp: []
  sign: []
tags:
- name: MQTT
  description: Obtain MQTT streaming/command certificate
paths:
  /iot-open/sign/certification:
    get:
      operationId: getMqttCertification
      summary: Get MQTT certificate
      description: Returns the MQTT broker connection parameters (broker url, port, protocol) and per-account credentials (certificateAccount / certificatePassword) used to subscribe to device quota/status streams and publish set commands over MQTT.
      tags:
      - MQTT
      responses:
        '200':
          description: MQTT certificate retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationResponse'
              example:
                code: '0'
                message: Success
                data:
                  url: mqtt.ecoflow.com
                  port: '8883'
                  protocol: mqtts
                  certificateAccount: open-abc123
                  certificatePassword: '********'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    CertificationResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          data:
            type: object
            properties:
              url:
                type: string
                description: MQTT broker hostname.
              port:
                type: string
                description: MQTT broker port (typically 8883 for mqtts).
              protocol:
                type: string
                description: MQTT protocol (mqtts).
              certificateAccount:
                type: string
                description: MQTT username for this account.
              certificatePassword:
                type: string
                description: MQTT password for this account.
    Envelope:
      type: object
      description: Standard EcoFlow response envelope.
      properties:
        code:
          type: string
          description: Result code; "0" indicates success, any other value is an error.
        message:
          type: string
          description: Human-readable result message.
      required:
      - code
      - message
    ErrorResponse:
      $ref: '#/components/schemas/Envelope'
  responses:
    Unauthorized:
      description: Authentication failed (bad accessKey, expired timestamp, or sign mismatch)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: '7000'
            message: Signature verification failed
    ServerError:
      description: Server-side error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: '500'
            message: System error
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: accessKey
      description: Access key issued in the EcoFlow developer console.
    nonce:
      type: apiKey
      in: header
      name: nonce
      description: Random nonce (typically a 6-digit number) regenerated per request.
    timestamp:
      type: apiKey
      in: header
      name: timestamp
      description: Unix timestamp in milliseconds at request time.
    sign:
      type: apiKey
      in: header
      name: sign
      description: HMAC-SHA256 signature (hex) over the ASCII-sorted request parameters concatenated with `accessKey`, `nonce` and `timestamp`, keyed by the secretKey.