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 at the integration's own address https://mcp.igh.app/r/{integration} (copied from its page). The platform opens the authorize page, which needs no sign-in: it names the agent, its platform and where it returns (never the house), and one button sends the request. 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; one agent has one request waiting per integration at a time. With the generic address https://mcp.igh.app (any of the home's API integrations), or with Sign in with the gateway account instead on the page, sign in with the gateway's cloud account first. A home the page doesn't find (the address is wrong, or Agent access or Cloud access is off) shows the sign-in; a gateway that isn't connected is said to be offline.

From the MCP server without a browser (terminal agents such as Claude Code): add the server with no credential, claude mcp add --transport http igh-home https://mcp.igh.app/r/<integration>. Without a credential it answers initialize and lists only about, request_access and check_access; any other tool is 401 with WWW-Authenticate: Bearer resource_metadata=…, so a client that signs in with OAuth still can. request_access { name, platform } (on the generic address with record too) starts the device flow below and answers the matching code and a code for check_access. Once an administrator accepts, check_access { code } answers the credential, once, with the exact claude mcp add … --header "Authorization: Bearer <credential>" command; store it securely and never repeat it in the conversation. One request per agent name and platform waits at a time.

The device flow (no browser at all: terminal agents, scripts, CLIs), on https://api.igh.app:

POST /v1/pair { "record": "https://mcp.igh.app/r/<integration>", "name": "Claude Code on Dana's laptop", "platform": "Claude Code" } → { code, userCode, interval, expiresIn }. record is the integration's own address (or its id); instead of it, "gateway": "<12-character id>" names the gateway (optionally with record). An address no home answers to (or whose integration has Agent access or Cloud access off) is 404 not_found.
Show the user userCode and ask them to approve it in the IGH 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 (the system keychain or a secrets store).
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.
Use the credential as Authorization: Bearer <credential> on the API, or on the MCP server: claude mcp add --transport http igh-home https://mcp.igh.app/r/<integration> --header "Authorization: Bearer <credential>". A credential works on the generic address and on its own integration's address; on another integration's it is 403. In Claude Code, /mcp → Authenticate is the browser alternative.

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.