Getting Started

Follow these steps to get started building your application using Derapi’s API. Use our SDKs for even faster integration.

Get credentials

If you don’t have your Derapi client_id and client_secret please visit https://derapi.com/get-started/ to sign up for a Derapi account.

Credential Types - The Derapi API can be used in two modes, Virtual and Production. Virtual mode credentials can be created using the link above and allow getting started using our API with Virtual Devices. To control real DERs please contact us ([email protected]) to request Production credentials.

Authenticate to Derapi

Derapi uses OAuth2 client_id and client_secret for authentication. Our authentication endpoint is https://auth.derapi.com/oauth2/token. Derapi access tokens expire after 1 hour. If your access token expires you should repeat the same process to obtain a new access token.

To acquire a bearer token:

$ curl -u client_id:client_secret \
       -d "grant_type=client_credentials" \
       -X POST https://auth.derapi.com/oauth2/token

The endpoint will respond with JSON similar to the following:

{
  "access_token": "eyJraWQiOiJTd2d0NEFiUCsxNnVTaFJDdnR5aVdGUnpHRlNVd3dcL2xLbUU5",
  "expires_in": 3600,
  "token_type": "Bearer",
  "expires_at": 1723843415.017463
}

Derapi IDs and URLs

Derapi assigns a unique ID for each resource type in order to maintain simplicity and consistency across vendors. Objects such as sites, inverters, and batteries will each have a unique Derapi ID.

Derapi IDs consist of a type tag (e.g. site for Sites, batt for batteries, etc) followed by a randomized, Derapi-assigned identifier unique to the resource being referenced. For example, a Derapi ID for a battery might be batt-3e754i27ugnhqbfv

List endpoints (e.g. Site list) will return these Derapi IDs under the id field of each returned record.

Endpoints pertaining to a specific resource instance (e.g. Site details) will include an {id} path parameter which should be filled in with a Derapi ID, for example:

https://api.derapi.com/batteries/batt-3e754i27ugnhqbfv

How to locate a Derapi ID using a vendor-native ID

While it is not necessary to use vendor-native IDs in the Derapi system, you may have a use case that requires discovering the corresponding Derapi IDs. To map your vendor ID to a Derapi ID use the GET requests of the corresponding resource list endpoints. Those endpoints include:

• Sites https://api.derapi.com/sites
• Batteries https://api.derapi.com/batteries
• Solar Inverters https://api.derapi.com/solar-inverters
• EV Chargers https://api.derapi.com/ev/chargers

Use the vendorID and vendor to query the list endpoint. The vendor enum list is available in API reference for each of the list endpoints. For example, to discover the Derapi ID of an SMA Device ID:

GET /solar-inverters?vendor=sma&vendorID=<DEVICE_ID>

The responses will then have values like this:

{
  "sites": [
    {
      "id": "site-uqrzz4i5brveubz3",
      "vendor": "sma",
      "vendorID": "654321"
    }
  ]
}

This table provides a reference for how each vendor names vendorID for Sites and Devices:

How to locate a vendor-native ID using a Derapi ID

Within the Derapi API, you should use Derapi IDs for the best experience. However, if you need to interface with an external system that requires vendor-native IDs, this section describes how to obtain them. To discover your vendor ID from a Derapi ID use the GET requests of the corresponding resource details endpoints. Those endpoints are:

• Site Details https://api.derapi.com/sites/{id}
• Battery Details https://api.derapi.com/batteries/{id}
• Solar Inverter Details https://api.derapi.com/solar-inverters/{id}
• EV Charger Details https://api.derapi.com/ev/chargers/{id}

Use the Derapi ID {id} to query the details endpoint. For example, to discover the SMA Plant ID of a Derapi ID:

GET /sites/{id}

The responses will then have values like this:

{
  "id": "site-uqrzz4i5brveubz3",
  "vendor": "sma",
  "vendorID": "654321",
  "name": "My Site",
  ...
}

Both id and vendorID are also present in each of the resource list endpoint responses.

Next steps

You can get started with the Derapi API right away by using our virtual mode, or read up on authorization for real devices.