Access to the local Enphase Envoy API through code

Introduction

In April 2022 I had a PV system installed, with a local Enphase Envoy as part of the configuration.

The Enphase Envoy acts as a management gateway for the Enphase system. Collecting, storing and forwarding data to Enphase for the consumer Enlighten datapool and application.

My installation consists of an IQ Combiner; but I believe these instructions are valid for any Envoy running software greater than version 7. At the time of writing my Envoy is running D7.0.85.

Some history

I was interested in the raw data coming from the PV system. During vendor selection I reviewed the access and APIs available; and Enphase seemed to have a good mix of capabilities.

At some point in late 2021/early 2022 access to a local Envoy gateway was changed to require a JWT access token. This caused many home automation and data logging integrations to break. The documentation from Enphase showed how to interactively get the token and login. I found no documentation on doing this automatically through code.

After much reading, reviewing multiple blogs and github repos, and trial and error – I have this now working.

Authentication flow

Firstly, there’s a lot of head scratching on this approach from Enphase. Yes – it protects access behind a token, but it’s all intended for interactive work. I can only surmise that the market for this is not the home integrator or API data scraper. I see Enphase pushing that persona towards the Enlighten API v4 – which has a different set of issues (which I’ll write about in the future).

So the flow:

• login, using Enphase username/password, to the Enphase Entrez token service
• https://entrez.enphaseenergy.com/login
• get a JWT access token
• https://entrez.enphaseenergy.com/entrez_tokens
• post this JWT to the local envoy
• https://localenvoy/auth/check_jwt
• get data
• https://localenvoy/APIendpoint

The third step of this, posting the JWT to /auth/check_jwt, does not seem to be documented anywhere.

Also, and most troubling, the JWT itself is returned as part of the body of a html page. Some regex is needed to extract the specific text string. This has risk in the event that the html document structure changes in the future.

I posted a sample PowerShell script here.

Using this approach, I now have data being pulled from the local IQ Combiner, parsed, posted to a NoSQL database, and then graphed.