> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gridshare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> ℹ️ 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 [developers@gridshare.com](mailto:developers@gridshare.com).

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

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

# API Response in JSON format
```

[OAuth 2.0]: https://oauth.net/2/