If you are an Enphase customer, you are likely aware that there have been some changes to the Envoy, which is where we gather our data - this thread is long and covers a LOT https://support.enphase.com/s/question/0D53m00006ySLuRCAW/unimpressed-with-loss-of-local-api-connectivity-to-envoys
TL;DR Envoys that are upgraded to firmware D7.x and later no longer have unauthenticated access, default credentials, or an easily crackable installer login - instead, you need to grab a JWT from the enlighten site. So while the good news is that we do still have local access, the bad news is that the token acquisition process is sketchy at best.
I wanted to start this thread as a place to gather thoughts, clarify issues that everyone is having, and pull together a list of issues and feature requests. For clarification, I am currently on Envoy firmware D7.0.107
A special thanks to all of those that have already put in tons of time and effort into the integrations - gtdiehl, jesserizzo, DanBeard, briancmpbll, edasque and numerous others that have contributed, I apologize, I know Iâve missed lots of you.
Token Acquisition Issues
Right now, most of the repos use the following process to gather the token:
httpx session out to either https://entrez.enphaseenergy.com/login or https://enlighten.enphaseenergy.com >> use englighten web credentials to login >> take the session cookie, username and envoy serial number to request the JWT from https://enlighten.enphaseenergy.com/entrez-auth-token?serial_num={} >> use the JWT as bearer auth to the local envoy API endpoints
There is frequently an issue with the 2nd step which results in a 401 unauthorized response from the enlighten service. This issue also frequently occurs with web logins to the enlighten web app, so I believe the issue to be partly (if not completely) on their side. There is no single programatic way that I am aware of to just hit a single endpoint for a token and be done.
It appears that there used to be a JWT validation endpoint on the envoy that needed to be accessed before other API endpoints would respond, but this no longer appears to be the caseâŚmaybe this is an older D7 firmware requirement?? Curious if anyone has background here (thanks to Erik for clarification: https://github.com/edasque/enphaseLocalToInfluxDB#authorization-flow)
On my envoy, it appears that a session cookie is generated automatically, without having to first post the JWT to the validation endpoint - the cookie was not required for the GET, only the JWT auth, with the cookie coming after the connection.
The token is valid for 6 months, but the expiration is coded in the exp field of the JWT - needs to be renewed before it expires.
Useful info
Known endpoints for the local Envoy:
https://envoy/backbone/application.js?version=07.0.107 Javascript of the app running (for your version, replace the D with a zero)
https://enlighten.enphaseenergy.com/ Enlighten logon page, will respond with a logon cookie; requires scraping page for login form
https://enlighten.enphaseenergy.com/entrez-auth-token?serial_num={} Returns entrez token as JSON; session must be logged in first, include _enlighten_4_session cookie
Enphase Energy - Enlighten | Sign in to Enlighten Programatic login page, returns login cookie; seems to be more reliable
https://entrez.enphaseenergy.com/tokens Programatic token page, returns JWT as string; takes cookie session, envoy serial number, and enlighten login
These are the two endpoints that I am using (as of a few days ago) in my repo https://github.com/jrutski/home_assistant_envoy_d7_fw , that seem to work a bit more reliably without presenting a 401 error.
Known Issues and Outstanding Feature Requests
- The data for the energy dashboard is not exported by the API, and needs to be added manually as a few calculated sensors. Not a huge issue, but I see this question come up a lot as new users start add the integration and the energy dashboard. Here are the sensors I use:
- sensor:
name: Grid Import Power
state_class: measurement
icon: mdi:transmission-tower
unit_of_measurement: W
device_class: power
state: >
{{ [0, states('sensor.envoy_xxxxxxxxxxxx_current_power_consumption') | int - states('sensor.envoy_xxxxxxxxxxxx_current_power_production') | int ] | max }}
- sensor:
name: Grid Export Power
state_class: measurement
icon: mdi:transmission-tower
unit_of_measurement: W
device_class: power
state: >
{{ [0, states('sensor.envoy_xxxxxxxxxxxx_current_power_production') | int - states('sensor.envoy_xxxxxxxxxxxx_current_power_consumption') | int ] | max }}
- For the systems that have an Enpower smart switch (ATS) Grid Status needs to be added - it appears to be exposed both in the ensemble inventory endpoint (/ivp/ensemble/production.json) or the home endpoint, though I donât think Iâve seen it being queried (/home.json)
While I think it would be nice to be able to automatically drop loads when the grid is down, I donât think the current polling interval is short enough to prevent a shutdown. I had this happen the other week, with the dryer and A\C running, I exceeded the battery capacity while the solar micros were ârebootingââŚthereâs only 10 seconds of peak output.
- Systems that include batteries do not appear to expose meters for in/out to the batteries, or at least not the newer encharge 3/10 systems. The /production.json endpoint does have SOME storage data, but only for the older AC Battery systems (thus the âacbâ)
What does this mean? It means your consumption readings will be completely off - becasuse the battery is essentially a home load. So there is no way to tell what the actual loads in the house are vs charging and discharging the battery. Iâve dug through tons of the known endpoints and have yet to figure out where this data might be from an encharge system.
As I mentioned I just wanted to get my thoughts in one place, and hopefully we can find some more answers. Iâm happy to provide any API responses that anyone would like to see, or help in any way I can.
Thanks,
Jacob