Derapi makes it easy to acquire, use and maintain credentials for vendor APIs and devices. Acquiring vendor API credentials and authorizing system owner devices varies between DER vendors. This section contains instructions on how to get credentials for each vendor and associate customer-owned devices with your credentials.

Derapi credentials vs. vendor credentials

In order to use Derapi's API with real devices, you'll need to obtain Production mode credentials. Contact us ([email protected]) to request these credentials.

Your Derapi credentials will allow you to use the Derapi API to access any DERs for which you've been authorized. With most vendors, authorization is performed at either the device or the program level. The section below on Derapi Join explains how you can collect and store individual DER authorizations in Derapi's system, associated with your Derapi client credentials.

The table below summarizes the different categories of credentials that you may encounter when using Derapi:

Derapi Join

Derapi Join allows you to easily collect and store credentials obtained via authorization flows completed by system owners. Many vendors support OAuth 2.0-based flows allowing system owners to give their consent for access to their DERs, but vendors vary in the specifics of how they implement the standard. Derapi Join provides a unified mechanism for initiating authorization flows and securely storing the resulting credentials directly into Derapi's system for later use with our API.

Getting started with Join

The process of using Derapi Join consists of the following steps:

1. Provision client credentials for the vendor(s) you plan to support
2. Import those client credentials into Derapi
3. Create a Join Flow referencing the client credentials to use, and specifying a redirect URI
4. Use the authorize endpoint for you Join Flow to initiate system owner authorization sessions

The following sections explain each of these steps in more detail.

Provisioning client credentials

Most vendors require pre-registration for 3rd party applications (clients) that will be requesting system owner authorization. With Derapi Join, you can either complete this registration process on your own and import your client credentials into Derapi, or have us provision client credentials for you, depending on your needs.

The exact type of credentials needed to support Join varies by vendor. If you're planning to provision client credentials yourself and import them into Derapi, see the section below about vendor requirements for per-vendor details on the provisioning process. Once provisioned with the vendor, client credentials must be imported into Derapi via our vendor credentials APIs.

Importing client credentials

Once you've provisioned client credentails for the vendor(s) you wish to use with Join, you'll need to import them into Derapi using our vendor credentials API. See the documentation for our create vendor credentials endpoint for details on how to do this.

Here's an example showing how you might import Enphase Developer App credentials into Derapi:

$ curl \
  -X POST \
  -H "Authorization: Bearer ${DERAPI_TOKEN}" \
  -H 'Content-Type: application/json' \
  https://api.derapi.com/vendor-credentials \
  -d '{
    "name": "my-app",
    "credentials": {
      "vendor": "enphase",
      "type": "developerapp",
      "clientID": "'${ENPHASE_CLIENT_ID}'",
      "clientSecret": "'${ENPHASE_CLIENT_SECRET}'",
      "apiKey": "'${ENPHASE_API_KEY}'"
    }
  }'
{
  "id": "cred-rvu37v4fylnbuznf",
  "name": "my-app",
  "credentials": {
    "vendor": "enphase",
    "type": "developerapp"
  }
}

Imported credentials are assigned a unique identifer within Derapi's system (cred-rvu37v4fylnbuznf in this example). This identifier allows you to refer to these previously-stored credentials without needing to re-specify them.

You can use our list vendor credentials endpoint to see which vendor credentials have already been imported into Derapi and obtain their identifiers.

Note that importing client credentials does not immediately convey access to actual DERs. Most vendors require a separate step wherein the system owner provides their consent for access to their DER. Derapi Join can help you obtain this consent and manage the resulting device or system-level credentials.

Creating a Join Flow

Once your vendor client credentials are imported into Derapi, you can create a Join Flow. You can think of Join Flows as a reusable bundle of configuration that you will use to collect system owner consent and the resulting credentials for a specific use case (e.g. for enrollment into a particular program). Each Join Flow can support collecting system owner consent from one or more vendors, depending on how you configure the flow at creation time.

You can create a Join Flow using our create Join Flow endpoint. Here's an example showing how that might look for a flow that supports collecting system owner consent for use with Enphase Developer App credentials:

$ curl \
  -X POST \
  -H "Authorization: Bearer ${DERAPI_TOKEN}" \
  -H 'Content-Type: application/json' \
  https://api.derapi.com/join/flows \
  -d '{
    "vendors": [
      {
        "vendor": "enphase",
        "credentialsID": "cred-rvu37v4fylnbuznf"
      }
    ],
    "redirectURI": "https://example.com/auth-success"
  }'
{
  "id": "flow-1234567",
  "vendors": [
    {
      "vendor": "enphase",
      "credentialsID": "cred-rvu37v4fylnbuznf"
    }
  ],
  "redirectURI": "https://example.com/auth-success"
}

In this example, we've configured a flow (flow-1234567) which supports one vendor (enphase), using the Enphase client credentials created in an earlier example. This flow may now be used to create Join Sessions and collect system owner consent and the resulting system-level credentials.

Initiating a Join Session

Once a Join Flow has been created, it can be used an indefinite number of times. Each usage of a Join Flow is referred to as a Join Session. Join Sessions are ephemeral, and consist of a unique, client-provided state token, a flow ID, and a selected vendor.

You can initiate a new session by directing a system owner's browser to the authorize endpoint for your flow ID, which has the following format:

https://api.derapi.com/join/flows/{flowID}/authorize?vendor={vendor}&state={state}

You can see details on this endpoint in our API documentation. Note that unlike most Derapi API endpoints, this endpoint is publicly accessible, since it is intended to be accessed directly from system owner browsers. You should not provide a Derapi access token as part of requests to this endpoint, since doing so would potentially expose your Derapi access token to system owners.

This endpoint will construct an authorization URL for the vendor specified in the vendor query string parameter and redirect the system owner's browser immediately to it. This vendor must be one of the ones provided when the corresponding Flow was created.

Once the system owner gives their consent, the system owner's browser will be redirected back to a special Derapi endpoint, which will store the retrieved credentials securely within Derapi's system. Derapi will redirect back to the redirectURI that was specified when the Flow was created, injecting the following query string parameters:

1. The original state that was provided when the Join Session was initiated by calling the authorize endpoint; and
2. An enrollmentID, which you can use with our enrollments API to obtain information about the enrolled system or device

Using the collected credentials

System-scoped credentials collected via the Join process will be automatically stored for use by other endpoints within the Derapi API (for example, our sites endpoints). Note that Enaphse VPP has an asynchronous approval process, which may mean that the target system is not immediately accessible until approved by the vendor.

Vendor Requirements

This section outlines individual Vendor requirements to enroll customer devices.

Tesla

Requires an account to enroll customer devices. Create a Tesla API account by following these instructions. Store these credentials using the TeslaAppCredentials credentials object in the https://api.derapi.com/vendor-credentials endpoint.

Join will store an access_token and refresh_token. Tesla third party refresh tokens expire after 3 months but Derapi will automatically refresh.

Solis

Solis does not require developers to create an account to enroll devices.

Solis uses a custom authorization system using API ID and Key for each Solis portal account. Join will store these per-account credentials.

SMA

SMA requires an account to enroll customers. To create a SMA API account contact SMA and request credentials for the SMA Code Grant Flow. Also specify api.derapi.com/join/sma/auth-granted as redirect URL in your SMA config request. Store these credentials using the SMAOAuthCredentials credentials object in the https://api.derapi.com/vendor-credentials endpoint.

Join will store a per-system access_token and refresh_token and Derapi will automatically refresh.

SolarEdge

SolarEdge does not require developers to create an account to enroll devices.

SolarEdge uses a custom authorization system using an API Key. This key is retrieved from the SolarEdge Monitoring Portal. Join stores these per-account credentials.

Enphase Monitoring

Enphase requires an account to enroll customers and offers two options for enrolling and authorizing customer systems:

• If you are an Application Developer then follow the Enphase instructions to set up Developer account.
• If you are an Installer then follow the Enphase instructions to set up a Partner plan account.

Enphase Developer account

Follow the Enphase instructions to get an access_token and API Key. Store these credentials using the EnphasePartnerAppCredentials credentials object in the https://api.derapi.com/vendor-credentials endpoint.

Join will store an access_token and refresh_token. Enphase access tokens expire after 1 day and refresh tokens expire after 1 month but Derapi will automatically refresh.

Enphase Installer / Partner account

Follow Enphase instructions to get an access_token and API Key. Store these credentials using the EnphaseDeveloperAppCredentials credentials object in the https://api.derapi.com/vendor-credentials endpoint.

Enphase Grid Services

Enphase Grid Services requires a distinct authorization from that of Enphase Monitoring. Enphase Grid Services offers OAuth2 for enrolling customers. Upon request, Derapi will activate your Enphase Grid Services account and store the required credentials associated with your Client ID.

Derapi Join is required to enroll customers for Enphase Grid Services. Query the https://api.derapi.com/vendor-credentials endpoint for the vendor enphasevpp to find the reference to your EnphaseVPPCredentials.