Frequently asked questions

Got a question? We´re here to answer! If you don´t see your question here,
drop us a line on our Contact Page.

You can also look up the definitions of terms in our glossary.

What are you looking for?

API Access Control

General Approach

How do I get API key/client credentials?

Please get in touch with API Developer Support. They will set up client credentials for you.

Do I have to sign the contract for each plant that I want to monitor?

No, the contract includes the set-up of client credentials. You will be able to monitor any system to which you have access once you have obtained the credentials. There is no need for a contract for each plant.

What do I need to do if my installer or system-owner is not available anymore? How can I access to data?

The administrator has the same rights as an installer and can assign the system owner role to another user.

About the flows

Code flow: What is a redirect URL, how does it work?

The Authorization Code Flow transfers an Authorization Code for a token. Because you must also pass along your application's Client Secret during the exchange, which must always be kept secure and stored in your client, your app must be server-side. Therefore, redirect URLs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with either an authorization code or access token in the URL.

  • Access token is user-related, access only possible to the systems of the authenticated user.

  • Typically used in end-user (mobile) apps where consent can be given directly/online/synchronously via e.g., an SMA-Connect button.

Custom flow: What is the difference to Code flow?

When the client is seeking access to protected resources of another or a specific resource owner, as previously agreed upon with the authorization server ((sandbox-), it has the ability to seek an access token solely through its client credentials. That means:

  1. Access Token is client-based, allowing access to systems from many system owners (requires asynchronous consent).

  2. Normally used in O&M (web) applications (monitoring/reporting/alerting…), usually not used by the end user/system owner, but only by the O&M partner himself.

User Consent

Why does SMA require URLs to my app-logo, T&C and DataPrivacy? Why is it necessary?

SMA will present a user-consent/permission screen on behalf of your application access request. In order to setup your client credentials and configure the according permission-screen for your application, we will need to receive data from you which will be embedded on this screen. This includes an app-logo as well as the T&C and DataPrivacy URL of your application/homepage.

How does the system-owner permit the 3rd party applications to access his system data?

From a user perspective, the 3rd party authorization request will look the same for both flows. The plant owner will need to login with his user credentials on the SMA systems, review the information on the user-consent screen and take his decision to permit or decline the access request.

How often will 3rd party applications need to execute the user-consent flow?

SMA user (being plant owner of a certain number of systems) will grant access to all of his systems at a certain point in time. User-consent will remain to be valid until actively revoked by the user on the SMA portal

In case the (commercial) plant owner adds new systems to the portal over-time, user-consent needs to be re-executed to gather the permission for these new systems (“Permission-scope change”). The older consent will though remain to be valid to ensure access according to the prior permission scope assuming that the plant ownership for these plants still exists. Furthermore, a new (additional) consent-request may become necessary in the future, e.g. in order to enable the usage of a SMA Control-API.

Why do I receive an empty plant list/response on SMA Monitoring requests?

Most likely, you have not yet been provided with user-consent for system on the SMA custom flow. Using the Client-Token on the Monitoring API without a valid plant owner permission, will result in an empty response.

In which language is the consent request email sent to the resource owner in the custom flow?

The language setting of the resource owner's user profile in SP is used for distinguishing the language (currently either German or English) of the consent request eMail.

Why wasn't a permission request sent to the system owner?

The reason is mentioned in the response: the User used as loginHint is not a system-owner.

Why can I not see the Consent Screen?

The procedure is as follows: you must perform the bc-authorize step, which causes an eMail to be sent to the system-owner. The eMail contains a link which redirects you to a consent-screen, which is only accessible in ennexOS.  That is, you must be already-signed in to see the user consent screen (even if you only have Classic systems, the systems will be displayed in ennexOS anyway).

ennexOS and sunny portal

Where do I add or define plant ownership on existing PV-systems in SMA portals?

In the navigation “user management” on both SMA portals the new plant relationship (plantOwner) can be added to an existing SMA user account. Or you may invite a new user to the plant.

From a conceptual point of view, only one plant owner should be configured for each plant. Even though it increases complexity in the current ennexOS SP implementation, it is not yet prevented that more than one plant owner is configured for a given plant.

How can I access the User Management on SMA Sunny Portal? How can I set the “system-owner” flag on Sunny Portal?

a. To access the User Management on SMA Sunny Portals, the user must have at least an administrator or installer role.

b. Definition of the “plant owner"

  • On SP Classic the "plant owner" flag can be assigned to any user (role : admin, installer, user, guest)

  • On ennexOS the "plant owner" flag can be assigned to standard user and administrator

Once this “ownership flag” has been defined for the user, the user has the permission to decide on the 3rd party application request.

What data refresh rates are available for SMA systems and devices?

Please make yourself familiar with the following description & dependencies to optimise the request-and data-traffic load of our data integration. There is no need to request data more often than the processing speed (on Classic systems), because no new data will be available.

Most importantly, there is a huge difference regarding the supported data refresh rates for systems on Sunny Portal Classic (Webconnect, Home Manager, Cluster Controller) and the new ennexOS Sunny Portal with Data Managers.

For Sunny Portal Classic systems new data sets are only provided on completion of data processing (validation, aggregation of time-intervals). Even if the system/device uploads new (raw) data every 15 minutes it takes up to 2hours until the new data is provisioned on the UI (and API alike). The refresh rate can be reduced to about 15min by obtaining a “Professional Package” for the individual system (in certain countries). The “Pro” Option can be purchased on “Sunny Portal Online Store”.

On the ennexOS we changed the procedure. Data Manager uploads data as a default every 5 minutes (depending on the communication profile set in the portal). The difference now is the processing of the data. We do the processing on the fly when you either select a view in Sunny Portal or access is it via the API.

--- Classic ----
Home Manager
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

Cluster Controller
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

--- ennexOS ----
Data Manager
Upload: every 5 minutes
Processing: On the fly

Where do I find the plant and device IDs in Sunny Portal UI?

In SP powered by ennexOS UI, the Monitoring API plant and device IDs are part of the URL when navigating to the corresponding plant / device.

In SP UI, the Monitoring API plant ID is part of the URL when clicking on the PV System Logbook navigation tree item. The Monitoring API device IDs are not displayed on SP UI.

What is the significance of Log-IDs, Event-IDs, and MessageTag-IDs in the context of ennexOS vs. classic plants and devices?

For ennexOS plants and devices, the logId returned in logs endpoint is the Event ID displayed in SP powered by ennexOS Event monitor.

The messageTagId identifies the message text returned in the logs endpoint.

For classic plants and devices, the logId is currently empty, as the Event ID is not persisted in SP backend.

We plan to implement a mapping from messageTagId to Event ID which is unique in most cases, so that also for classic plants and devices, the logId will contain the Event ID.

Why do I not get the complete measurement set?

If certain properties of a measurement set are unavailable/not configured, they will be excluded from the result set. Kindly review the /measurements/sets endpoint before utilizing/monitoring a specific period/ timespan. Please also check your configurations in the Portal(s).

Which PV-systems are stored on which portal backend?

Our Monitoring-API will provide access to systems stored in either portal backend. To setup a new system you will either use SMA Sunny Portal or Sunny Portal powered by ennexOS.

In the API-request you will not need to define the specific portal backend. You can differentiate the PV-system source by the provided plantID-format. SP Classic systems identifiers are defined as GUID (8-4-4-4-12) value and the ennexOS systems id values are pure number format.

Where and how to configure that a specific portal user is the SMA resource/plant owner?

The resource owner of a system must be defined for new plants in the PV-plant setup wizards flow or for existing plants in the user administration. Eligible SMA resource owners must be configured on Sunny Portal and SP powered by ennexOS alike.

How can I add a new plant and see that it is available for data access?
  • 1. Pre-condition
    Make sure than any related system has a system-owner (user) defined. For SunnyPortal systems in system configuration > user management > flag "system-owner". For ennexOS systems, the user needs to have owner-role.

  • 2. Adding new systems

    • 2.1System-owner with existing 3rd party application approval in place

      • 2.1.1Login to Sunny Portal powered by ennexOS and navigate to 3rd party application menu. Click on edit button on 3rd party application, select additional systems (owned by user) to be approved.

      • 2.1.2Alternatively, the 3rd party client can re-initiate the bc-authorize for the additional access scope (new systems) by using the owners’ eMail as LoginHint. Here the owner has to re-approve the (new) access scope request sent by SMA eMail.

  • 3. New System-owner who have not granted the initial approval.

    • 3.1 Use the bc-authorize flow with loginHint (owners eMail address) to trigger the initial permission request to be send out to the owner by SMA (via eMail).


How long are the refresh tokens valid?

The refresh tokens are currently valid for 2 days. This value may change in the future. When using the refresh token every 2 days, the session can be extended up to a maximum of 30 days (then the session max is reached).

Is there a solution in which tokens don’t expire?

Please take a look at Developer Page You will be informed on how to use the optional scope = offline_access to get an “offline-token”. This solution will lead to no expiration of a token.

For which period does the data refer to?

If you pull data in which periods are listed as following:



The data refers to the first period.

The JSON raw data contains a timestamp (Time) value. What exactly does that mean? Is that a UTC_START or an UTC_END date time?

The timestamp refers to UTC_END.

Is the data an average value?

No, the data for the given timestamp is a Mean value. The value includes data which is before the timestamp.


Which timebase resolution does the Monitoring API data provide?
  • In (classic) plants, the resolution in which the data should be provided in the UI and thus also via the Monitoring API was initially configured for each system during installation (and can no longer be changed).

  • For ennexOS plants, the data is normally uploaded at least every 5 min to the ennexOS backend and thus, normally, can be provided in 5min intervals. For some properties, the interval might be different, see e.g. GridSettings properties.

In our Monitoring API design you cannot request a specific resolution for measurement data and periods “Recent”, “Day” and “Week” as you will be served the highest resolution available. Thus for converting W to kWh, you must use the given timestamps of the provided data in order to do the transformation.

Please be aware, that on Sandbox environment, only ennexOS plant data is simulated with a 15min resolution as this environment is only meant for setting up an application initially.

Why is data missing from the response of the monitoring endpoint?

If some properties of a measurement set are not available (null) for the requested timespan, then they are not contained in the result set.

If no data is available for the whole timespan, then an empty list is returned.

Example: Request for weekly measurement data (from Mar 1 -> Mar 8), but the plant was not communicating for the last two days of that span. What does the response look like?

Response: Data available between 1st and 8th of May would be provided, thus from 1st to 6th of May. For the 7th and 8th of May, no measurement sets would be returned, if no data values at all are contained in our backend (so it depends also the measurement set properties).

Are total energy values preserved in the event of a hardware swap? For example, if a plant has a meter or inverter replaced, are the reported lifetime energy totals still accurate once the new hardware is online?

Yes, old data is kept in our backend. In the Portal UIs, you can see this data of deactivated devices. Also e.g. the energy balance of such a plant would still contain the values of the deactivated devices, as the historical data is kept untouched.


What is the difference between LiveAPI and MonitoringAPI?

The MonitoringAPI provides historical master-data, measurements and logs from plant-groups, plants, sub-plants, and devices whereas the LiveAPI provides 'live', more precisely near time data from plants/sub-plants/devices. However, the MonitoringAPI provides far more requests than the LiveAPI since it is designed to monitor. The LiveAPI provides live data directly from SMA systems and devices. In order not to burden the infrastructure unnecessarily, a correspondingly moderate and sensible basic call frequency must be implemented.


Which plants/systems are enabled for the GridControl API?

Each schedule command corresponds to a SEP 2.0 command. Unless otherwise noted, all supported commands can currently be executed for the following plants:

  • classic-WebConnect plants without self-consumption

  • classic plants with SMA HomeManager (currently limited to FeedInLimit command)

  • ennexOS plants with SMA DataManager (currently limited to FeedInLimit command, direct selling interface, labeled as "SPOT" on DataManager "local" User-Interface must be activated)

What exactly provides the GridControl API?

SMA GridControl API provides remote-control functions (schedule commands) to change system settings and operation modes of plants and connected devices. Schedule commands are treated as asynchronous tasks that can be executed from a given start time for a given duration and are assigned to a given plant via a schedule.

API Plans, Invoicing and Settlements

Why does an API service incur charges?

SMA sees its API portfolio as (B2B) SaaS-enabling product propositions, and it is constantly improving, operating, and supporting those API services and functional scopes. We have built a very strong global partner base in the last two years, and our service offering is heavily used by them. Therefore, according to SMA API price model principles, SMA charges for the consumption of a system in any given month and our per system (monthly flat) rate related to the system capacity including any device/inverter related calls.

Does the example on API Plan Page refer to one system only? Does the price refer to one month or the whole year?

It refers to one 50kWac system and for the whole year, if the system has monitored in only one month.

What are the prices in US$?

Same as EUR.

When will I receive an invoice?

Our SMA Invoice & Finance Team will send the invoice quarterly or annually.

Can I pay annually?

Yes, see
If you prefer an annual payment option in general, please inform the API Developer Support.

What means PU in the billing?

1 PU refers to 1 month.

I did not get a billing yet. What is the reason?

The Invoice & Finance Team will only create an invoice, if the consumption fee exceeds 1000 EUR. Otherwise, the invoice will be generated at the end of the year. See following example:

Q1 242€ -> no invoice

Q2 759€ -> invoice for 1001 € will be generated (Q1 + Q2)

Q3 450€ -> no invoice

Q4 450€ -> invoice for 900 € will be generated (Q3 + Q4)



User Management
The User Managment can be found in the ennexOS Portal and Sunny Portal. The User Managment gives information about the administration of user identities, access, and permissions within the Sunny Portal or ennexOS Portal. This includes creating, updating, and deleting user accounts, as well as assigning appropriate permissions to ensure users have adequate and secure access to the required resources (plants).

The role of an administrator has the right to set/define a role to a user (for example as a system-owner). The same applies for the role of an installer.

A plant is a collection of systems/devices. Example: Device A and Device B build a Plant X.

System owner
A system owner is the owner of a system (device). If a 3rd Party wants to access data of a specific system or plant, the 3rd Party will need to ask the system owner of the specific system or plant for permission > see User Consent.

Resource owner
Is the same as System Owner. "Resource" will be mentioned in the developing context, since the "resource" of data is a specific "system".

Client Credentials
In order to access to data with any of our SMA APIs, you will need to contact the SMA Developer Support Team first. Either with or with the contact form, which you will find on our SMA Developer Page.

Device ID
A Device ID is the ID of the device and will be needed when accessing data. If you want to know how to get the ID please see

Update frequency/ Refresh rate
The update frequence of data depends on the system. Classic systems usually have a lower update frequency and systems which integrated ennexOS have a higher update frequency.  However, it is possible to fasten the update frequency of a classic system with the Professional Package. See for more information.

3rd Party Application
In general, a 3rd Party Application is an API consuming application, which provides a company with a e.g. an Energy Managment System for all their systems.

Custom flow

Code flow

User consent
SMA authorization server validates the request to ensure that the client is authenticated, and all required parameters are present and valid. If the request is valid, the authorization server will notify the SMA resource owner by eMail and inform him about your clients´ access request on his resources. This eMail will include a link to prompt the user login (user authentication) and present the user consent screen.

Refresh token
A token that manages a request session is a refresh token. The refresh token expires after a certain period of time, which triggers the beginning of a new session. Currently, the refresh tokens are only valid for two days.

Redirect URL

Permission Request

Add plants

Description: This field represents the amount of electrical energy generated by the photovoltaic (PV) inverters in the solar power system.

Description: This field indicates the total electrical energy consumed by a location or property. It encompasses all electricity used by the appliances, devices, and systems within that location, both from the grid and from the inverters.

Description: This field shows the rate at which energy is being stored in the battery of the solar power system. It represents the power flow into the battery when it is being charged.

Description: This field represents the rate at which energy is being drawn from the battery of the solar power system to power electrical loads. It indicates the power flow out of the battery when it is discharging.

Description: Total generation combines both the energy generated by the inverters (pvGeneration) and any other power sources, such as the grid or backup generators. It represents the overall electrical energy produced on-site.

Description: Self-consumption refers to the portion of the energy generated by the inverters (pvGeneration) that is used on-site to power the property's electrical loads. It is the energy generated by the inverters that doesn't go back to the grid.

Description: This field provides the percentage or ratio of the energy generated by the inverters (pvGeneration) that is used on-site (selfConsumption) relative to the total energy generated (totalGeneration). It helps assess how efficiently the generated energy is utilized within the property.

Description: Self-supply is similar to self-consumption, but it includes not only the energy used on-site but also any surplus energy that is stored in the battery. It represents the portion of energy that is consumed on-site or stored for later use.