Working with Production Devices

To access vendor DERs use Production mode credentials.

Vendor Authentication

When clients make requests against Derapi, they include an OAuth Bearer token for each vendor to which a they have access. To accommodate multiple bearer tokens in one HTTP request, the client includes one header per backend. The headers take the form X-Authorization-<vendor>: Bearer ${bearer} where <vendor> is one of the backends Derapi supports, e.g., sma, solis, solaredge, enphase, enphasevpp, tesla, etc. The X-Authorization-* headers follow the syntax and semantics of RFC 6750. Clients obtain bearer tokens directly from each backend.

Vendor-specific authentication requirements

• Solis is authorized with X-authorization-solis: Basic $(base64 <<< "${key_id}:${key_secret}")
• Solaredge is authorized with X-Authorization-solaredge: ${api_key}
• Enphase requires both X-Authorization-enphase: Bearer ${bearer} and X-enphase-api-key: ${enphase_api_key}

Example: client acquires and transmits tokens

To acquire a bearer token from SMA, the client posts this request to SMA's token endpoint:

$ curl -u ${sma_client_id}:${sma_client_secret} \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d grant_type=client_credentials&scope=monitoringApi:read \
       -X POST https://auth.smaapis.de/oauth2/token

SMA will respond with JSON similar to the following:

{
 "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA",
 "expires_in":300,
 "refresh_expires_in":1800,
 "refresh_token":"eyJhbGcIgOiAiSldUIiwia2lkIiA6ICJhNmJlZjg4NS0yNT",
 "scope":"monitoringApi:read gridControlApi_EnergyTrader:read"
}

The client repeats this process for other backends, saving the value of access_token each time (eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA in this example). Credentials and scopes will differ for each backend.

Example Derapi API request

Having acquired tokens for Derapi and all relevant backends, the client passes them as headers in requests to Derapi. For example, a client can use this command to retrieve a list of all solar inverters from Derapi:

$ curl -H "Authorization: Bearer ${derapi_access_token}" \
       -H "X-Authorization-sma: Bearer ${sma_access_token}" \
       -H "X-Authorization-solis: Basic $(base64 <<< "${key_id}:${key_secret}")" \
        https://api.derapi.com/solar-inverters

Derapi's response may look like this:

{
  "solar-inverters": [
    "https://api.derapi.com/solar-inverters/solr-4a754i27ee1cb550",
    ...
    "https://api.derapi.com/solar-inverters/solr-4r224g27ff1cb900",
    "https://api.derapi.com/solar-inverters/solr-4i754s27221cb001",
  ],
  "errors": {}
}