Authentication and Accept agent

Credentials

Every request but GET /v1/about carries Authorization: Bearer <token> (on the WebSocket upgrade, ?token=<token> works too). Tokens look like igh_{kind}_{gateway}.{integration}.{link}.{secret}:

Kind	Made by	Lasts	With `agent_access: off`
`igh_key_…`	Create key on the integration's page	until revoked	keeps working
`igh_agent_…`	Accept agent → Accept	until revoked	suspended
`igh_session_…`	Accept agent → Accept for this session	1 hour after its last use, 12 hours at most	suspended

A hosted agent (Claude, ChatGPT and other MCP platforms) never holds a lasting secret: it gets 1-hour igh_agent_… access tokens and refreshes them through OAuth.

Store it securely, reuse it. A key or agent token is shown once. Keep it in the system's secret store (Keychain, Credential Manager, libsecret, a vault), never in source, logs or chat. Reuse it on every run; ask for a new one only after 401 unauthorized.
What ends it: Revoke on the integration's page, deleting the integration, or (agents and sessions) turning Agent access off, which suspends them until it is on again (agent_access_disabled). A session past its time answers 401 session_expired. A disabled integration answers 403 record_disabled.
Where it was used is shown on the integration's page (last used, home network or cloud); an unused key or agent shows as stale after 90 days, but never expires for that.
Changes made with a credential appear in the activity log as API: {integration} (a key) or Agent: {name} via {platform}.

Accept agent

An agent never gets a credential without an administrator of the home saying yes in the IGH app.

From an MCP platform (Claude, ChatGPT, …): add the connector https://mcp.igh.app (any of the home's API integrations) or the integration's own address https://mcp.igh.app/r/{integration} (copied from its page). The platform opens the sign-in page: sign in with the gateway's cloud account. The page shows a matching code; every administrator of the home is notified (integrations.approve) and sees the same code, the agent's name and platform, and the integration it would get. They choose Accept, Accept for this session (not offered to hosted platforms) or Deny. For the same agent again they may Replace its old credential or Add another. A request waits about 10 minutes.

The device flow (scripts, CLIs, agents without OAuth), on https://api.igh.app:

POST /v1/pair { "gateway": "<12-character id>", "name": "Garden script", "platform": "Python" } (optionally record, an integration id) → { code, userCode, interval, expiresIn }.
Show the user userCode and ask them to accept it in the app.
Poll POST /v1/pair/token { "code": "<code>" } every interval seconds. Until then the answer is { "error": "authorization_pending" } (slow_down when polled too often: wait 5 seconds longer). Then { access_token, token_type: "Bearer", kind }, handed out once: store it securely.
access_denied: an administrator said no. Don't ask again right away; tell the user. expired_token: nobody answered in time; start again only if the user wants to.

Requests are rate-limited per home (5 a minute, 30 an hour). The integration needs Agent access on (integrations.record); a hosted platform also needs Cloud access on.

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