ℹ️
You need credentials to interact with the API
After creating an account we will securely provide you with a client_id and
client_secret pair. At this moment you cannot sign up online.

To begin building with the Gridshare Customer API, reach out to support at [email protected].

If you are already connected with the team and ready to begin, follow the Authentication steps below.

Getting an Authorization token with Code Grant Flow

OAuth2 authorization code flow is a secure way for a Partner to get permission to access a Gridshare Customer's data on another service without the user having to give the app their password. If you are a pre-registered Gridshare Partner, you can use this flow to access the Gridshare Customer API.

1. Redirect the user to the Gridshare Login page

GET https://lunar-customer-prod-us-west-1.auth.us-west-1.amazoncognito.com/oauth2/authorize?response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=lunar/device.read lunar/device.write

client_id is your client ID you will have received during onboarding. redirect_url is the URI on your domain to receive the callback. Set state to a random string (and verify it in the next step).

scope is the permissions requested:

lunar/device.read: Allow permission to access device metadata and telemetry (excluding plans)
lunar/device.write: Allow permission to make changes to your devices including changing operation mode
lunar/plan.read: Allow reading existing device plans
lunar/plan.write: Allow sending plans to a device

2. Handle the callback in your APP

The browser will be redirected back to your app:

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

Ensure that the state value matches the value sent in step 1.

3. Exchange the code for tokens

POST lunar-customer-prod-us-west-1.auth.us-west-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=authorization_code&
client_id=1example23456789&
code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&
redirect_uri=com.myclientapp://myclient/redirect

The Authorization header should contain your client ID and secret in the form Basic base64(client_id>:<client_secret>).

client_id is set to your client ID.

code is the value passed in step 2.

The response to this will contain your access and refresh tokens.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJra1example",
    "id_token": "eyJra2example",
    "refresh_token": "eyJj3example",
    "token_type": "Bearer",
    "expires_in": 3600
}

4. Refresh the access token

The access_token returned in step 3 is only short lived. You can refresh it using the refresh_token:

POST lunar-customer-prod-us-west-1.auth.us-west-1.amazoncognito.com/oauth2/token >
Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZGpjOTh1M2ppZWRtaTI4M2V1OTI4OmFiY2RlZjAxMjM0NTY3ODkw

grant_type=refresh_token&
client_id=1example23456789&
refresh_token=eyJj3example

Sending API requests

curl -s -H "Authorization: Bearer ${access_token}" "https://${api_base_url}/api/v1/devices"

# API Response in JSON format