Quickstart

This walk-through uses curl and assumes you have already registered an OAuth client. Replace the base URL, client credentials and device ID with your own.

1. Send the user to the authorization page

Build the authorization URL and open it in the user’s browser:

https://api.splashmepool.com.au/api-gateway/v1/oauth/authorize
  ?response_type=code
  &client_id=sm_ab3de5fg7h_my-pool-app
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &scope=profile
  &state=9f2c1a

The user signs in with their SplashMe email and password. On success the browser is redirected to your redirect_uri with code and state query parameters. Check that state matches what you sent.

2. Exchange the code for tokens

POST/api-gateway/v1/oauth/token

curl -X POST https://api.splashmepool.com.au/api-gateway/v1/oauth/token \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d client_id=sm_ab3de5fg7h_my-pool-app \
  -d client_secret=sm_secret_0123456789abcdef0123456789abcdef

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "scope": "profile"
}

The authorization code is valid for 5 minutes and can be used once. The access token lasts 24 hours and the refresh token 30 days.

3. List the user’s controllers

GET/api-gateway/v1/user/sites

curl https://api.splashmepool.com.au/api-gateway/v1/user/sites \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "status": "SUCCESS",
  "data": {
    "sites": [
      {
        "objectId": "Q1w2E3r4T5",
        "name": "Home",
        "city": "Sydney",
        "state": "NSW",
        "device_list": [
          { "objectId": "Zx9Yw8Vu7t", "deviceId": "02_53_4D_00_00_01", "tag": "Backyard pool", "online": true }
        ]
      }
    ]
  }
}

deviceId is the identifier you use in every device endpoint.

4. Read the dashboard

GET/api-gateway/v1/iot-shadow/device/{deviceId}/dashboardInfo

curl https://api.splashmepool.com.au/api-gateway/v1/iot-shadow/device/02_53_4D_00_00_01/dashboardInfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "status": "SUCCESS",
  "data": {
    "dashboard": {
      "actual_ph": 74,
      "actual_orp": 652,
      "d_ph": 74,
      "d_orp_mineral": 650,
      "actual_pump_speed": 60,
      "actual_flow_rate": 180,
      "main_pump_status": 99,
      "heater_state": false,
      "chemistry_stable": true
    }
  }
}

pH values are multiplied by 10, so 74 is pH 7.4. ORP is in millivolts. The field reference is in Reading state.

5. Turn the pump on

POST/api-gateway/v1/iot-shadow/device/{deviceId}/setPumpInfo

curl -X POST https://api.splashmepool.com.au/api-gateway/v1/iot-shadow/device/02_53_4D_00_00_01/setPumpInfo \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"aux_switch_state":1,"aux_type_code":31,"pump_speed":60,"aux_slot_num":0}'

A 200 with "status":"SUCCESS" means the controller acknowledged the command. Pump and equipment writes wait up to 10 seconds for the controller’s reply; chemistry and schedule writes up to 3 seconds. Add the time spent waiting behind other commands to the same controller.

Next steps

• OAuth2 in depth: PKCE, refresh, error handling.
• Device API v1: every endpoint, field and range.
• Rate limits and throttling: how to pace requests to one controller.
• Device API v2 for controllers on firmware 2.5.46 or later.