Postman

The Postman package

To try the API by hand, import the Postman package from the public repository's postman/ folder (or download it below): the HTTP collection with every operation, the authorization flows and the refusals; an environment each for the home network and the cloud; and the WebSocket requests with their saved ClientMessage messages. It is generated with these pages, so it always matches the reference. On the home network, pin the gateway's CA first (GET /v1/gateway/tls, TLS and CA pinning).

IGH home API in Postman

Version 1.1.0. Generated from the API's OpenAPI and AsyncAPI documents with the rest of https://developers.igh.app: nothing here is edited by hand.

1. Trust the gateway's CA (local environment)

On the home network the gateway answers on port 8490 with HTTPS signed by its own CA. Pin that CA in Postman; never turn off SSL certificate verification (Settings → General → SSL certificate verification stays on).

1. Get ca.pem, either:
   • in the IGH app: Settings → Integrations → the API integration → Download CA (igh-<serial>-ca.pem; it shows the SHA-256 fingerprint too);
   • or through the cloud: select a cloud environment, set {{token}} (step 4), send TLS → Gateway CA (to pin), and save the answer's ca as ca.pem (the Visualize tab shows it to copy). Compare fingerprint with openssl x509 -in ca.pem -noout -fingerprint -sha256.
2. Postman → Settings → Certificates → CA certificates: turn it on and select the file.
3. Select the IGH local environment and set serial (the gateway id, lower case). Postman reaches igh-<serial>.local through mDNS; where that doesn't resolve, put the gateway's LAN address in baseUrl and wsUrl (https://192.168.1.20:8490/v1): the certificate names it too.
4. After the CA is regenerated in the app, repeat from 1.

2. Import

1. Postman → Import → select the collection and the three environments (drag them in together).
2. For the WebSocket requests: see WEBSOCKETS.md (the v3 folder, or a request saved by hand).
3. In the environment selector (top right) pick one.

3. The environments

Switching the environment is the only change between the home network and the cloud: every request uses {{baseUrl}} and {{token}}. The device flow, OAuth and MCP always go to a cloud (pairBase, recordUrl).

Secret variables keep their current value on this computer only. No environment holds a credential or an id: fill them in Postman.

4. Get a credential

Each folder under Authorization runs top to bottom (send each request, or Run folder in the Collection Runner) and ends with {{token}} set.

(f) holds the refusals: no token, a bad or revoked one, Agent access or Cloud access off, another integration's credential on its address.

5. Run

1. Getting started → House fills the id variables (deviceId, lightId, sceneId, roomId, …) with the house's first of each kind, only while they are empty: clear one to pick again, or set it to the device you want.
2. Smoke run (read-only) → Run folder: every read, nothing switched or created.
3. The other folders top to bottom. Requests named [switches a device] operate real units. Scenes, Automations and Schedules create one test object each (a scene of one delay, a disabled automation, a paused schedule): the API never deletes, so remove them in the app.
4. Errors and edge cases provokes each refusal; some need a setting of the integration changed first (the request says which).

Every request checks its status. A refusal is checked for { error: { code, message } }, and the console (View → Show Postman Console) prints its appAction (the app screen that does what the API won't) and retryAfter. Through the cloud, 50 requests a second and 600 a minute per home: past that, 429 with retryAfter.

Guides: https://developers.igh.app · Reference: https://developers.igh.app/reference.html

The WebSocket in Postman

/v1/stream carries requests as messages, subscriptions and pushed events (AsyncAPI: https://developers.igh.app/asyncapi.html).

Postman sends WebSocket requests, but its Collection v2.1 file format (the collection .json) can't hold them: that is a limit of the file format, not of Postman. Postman v12's Collection Format v3 can, so the WebSocket requests come as a v3 collection beside it; the same requests can be saved by hand in any version.

The URLs

Authenticate the upgrade with Authorization: Bearer {{token}}, or ?token={{token}} when a client can't set headers: the gateway and the cloud both accept the query token on the upgrade (the cloud strips it before relaying; on HTTPS requests only the header counts). On the home network the CA pinned in README step 1 applies; keep SSL verification on.

Option A: the v3 collection (Postman v12)

collections/IGH WebSocket/ is a Collection Format v3 collection: one YAML file per request (Stream (Authorization header), Stream (token in the query)), each with every message below saved. Bring it in with Import → drag the IGH WebSocket folder, or open a folder holding postman/collections/IGH WebSocket in Local View (Native Git). Select an IGH environment, Connect, pick a saved message, Send.

Option B: by hand (any Postman version)

1. New → WebSocket. URL: {{wsUrl}}.
2. Headers: Authorization = Bearer {{token}} (or the URL {{wsUrl}}?token={{token}}).
3. Save it into a collection of its own, "IGH WebSocket" (a WebSocket request in the HTTP collection makes it a multi-protocol collection, with fewer features).
4. For each message below: paste it into the message box, set the type to JSON, Save message with its name. Variables ({{lightId}}) are replaced when sent.
5. Connect, then send a saved message.

The messages to save

A request message { id, method, path, query?, body? } (path with /v1, as on HTTPS) is answered { id, status, body }; { id, subscribe: [...] } chooses the topics (state, sensor, scene, exposure; all four until a client subscribes).

Subscribe: state

Only state events from now on (answered { id, status: 200, body: { subscribed } }).

{
  "id": "subscribe-state",
  "subscribe": [
    "state"
  ]
}

Subscribe: sensors

Only sensor events from now on (answered { id, status: 200, body: { subscribed } }).

{
  "id": "subscribe-sensor",
  "subscribe": [
    "sensor"
  ]
}

Subscribe: scenes

Only scene events from now on (answered { id, status: 200, body: { subscribed } }).

{
  "id": "subscribe-scene",
  "subscribe": [
    "scene"
  ]
}

Subscribe: exposure

Only exposure events from now on (answered { id, status: 200, body: { subscribed } }).

{
  "id": "subscribe-exposure",
  "subscribe": [
    "exposure"
  ]
}

Subscribe: everything

All four topics (what a new socket gets until it subscribes).

{
  "id": "subscribe-all",
  "subscribe": [
    "state",
    "sensor",
    "scene",
    "exposure"
  ]
}

Request: state now

GET /v1/state over the socket: read it once after (re)connecting to catch up.

{
  "id": "state",
  "method": "GET",
  "path": "/v1/state"
}

Command: light on [switches a device]

A request over the socket, answered { id, status, body } as over HTTPS. Switches a real device.

{
  "id": "light-on",
  "method": "POST",
  "path": "/v1/devices/{{lightId}}/control",
  "body": {
    "op": "set_power",
    "args": {
      "on": true
    }
  }
}

Command: light off [switches a device]

A request over the socket, answered { id, status, body } as over HTTPS. Switches a real device.

{
  "id": "light-off",
  "method": "POST",
  "path": "/v1/devices/{{lightId}}/control",
  "body": {
    "op": "set_power",
    "args": {
      "on": false
    }
  }
}

Keep-alive (no ping message: a cheap request)

The stream has no ping message, and a text that is not JSON (ping) closes it (4400 invalid_request). WebSocket ping frames are answered by the server; to see traffic, send this cheap request.

{
  "id": "keep-alive",
  "method": "GET",
  "path": "/v1/about"
}

What arrives

state

A unit's or gang's new state.

{
  "event": "state",
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light",
  "class": "light_dimmer",
  "state": {
    "on": true,
    "bri": 40
  },
  "at": 1760780000000
}

sensor

A sensor reading or detection.

{
  "event": "sensor",
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-hall-sensor",
  "class": "sensor",
  "state": {
    "motion": true,
    "lux": 120
  },
  "at": 1760780000000
}

scene

A scene runs (running true, then false).

{
  "event": "scene",
  "house": "Cohen Home",
  "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:scene:s-evening",
  "class": "scene",
  "state": {
    "running": true
  },
  "at": 1760780000000
}

exposure

What the integration shows changed: read GET /v1/house again.

{
  "event": "exposure",
  "house": "Cohen Home",
  "at": 1760780000000
}

answer

The answer to a request message.

{
  "id": "light-on",
  "status": 200,
  "body": {
    "house": "Cohen Home",
    "device": "8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-kitchen-light",
    "state": {
      "on": true,
      "bri": 40
    }
  }
}

error (rate limited, the socket stays open)

Through the cloud, a message past the limit.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this home. Wait and try again.",
    "retryAfter": 1
  }
}

error (before a close)

A credential that stopped passing: this frame, then close 4403 agent_access_disabled.

{
  "error": {
    "code": "agent_access_disabled",
    "message": "Agent access is off for this API integration.",
    "appAction": "integrations.record"
  }
}

Errors and close codes

• A refused upgrade is the HTTP status with the error body (401 without or with a bad credential, 403, 429 past 20 sockets per home through the cloud, 503 gateway_offline). Postman shows it as the handshake's response.
• A message that is refused (bad JSON shape, 413 over 16 KiB, 429 rate_limited with retryAfter through the cloud) is answered with an error frame or { id, status, body }; the socket stays open.
• A text that is not JSON (ping) closes the socket with 4400 invalid_request.
• A credential that stops passing (revoked, Agent access or Cloud access turned off, the integration disabled) gets an { error } frame, then the close code 4000 + the HTTP status with the error code as the reason: 4401 unauthorized or session_expired, 4403 agent_access_disabled, cloud_access_disabled or record_disabled, 4404, 4429, and 4503 gateway_offline when the gateway leaves the cloud.
• On AWS (api.igh.app, api.staging.igh.app) the close carries no code: the error frame is the only signal.
• Reconnect with a backoff, then send "Request: state now" to catch up.

IGH home API 1.1.0. Generated from the doc source; do not edit.