This section the integration steps and requirements that partners need to follow for integration with the Futurehome public API, both for receiving data from Futurehome and sending commands to Futurehome devices.

Overview

Futurehome Partner Platform integrates with external partners using HTTP for both flow directions (sending data to partners and accepting data). These directions will be described as streaming (Futurehome → Partner) and

ingestion (Partner → Futurehome). Although they are correlated, different processes happen that require action items from both Futurehome and the integrating partner.

Streaming

Futurehome delivers data produced by devices in its system to external partner using the HTTP POST methods and JSON as data format. Wrapped in the JSON message are a series of events and request metadata (request id), so partner APIs can use request ids issued by Futurehome for debugging and fault finding purposes. Before data can be sent to a partner, onboarding has to be performed. The following example format describes the onboarding format and highlights data required from the integrating partner.

{
  "partnerCode": "examplePartner", -- issued by Futurehome
  "name": "Partner", 
  "description": "Partner HTTP integration",
  "integrationType": "HTTP",
  "integrationConfig": {
    "authentication": {
      "type": "OAuth2ClientCredentials", 
      "tokenEndpoint": "<https://partner.com/oauth2/token>", -- required from the partner
      "credentials": {
        "clientId": "xxxxxx-xxxx-xxxxxx", -- required from the partner
        "clientSecret": "yyyy-yyyy-yyy-yyy-y-y-y", -- required from the partner
        "scope": "client_credentials_scope_1 client_credentials_scope_2 scope3", -- required from the partner
        "grantType": "client_credentials",
      }
    },
    "authorization": {
      "type": "HeaderBearerToken", -- required from the partner
      "key": "" -- required from the partner, if not Authorization Bearer
    },
    "batchSize": 150, -- configured by Futurehome
    "streamEndpoint": "<https://partner.com/streamEndpoint>" -- required from the partner
  },
  "allowedServices": [
    "meter_elec",
    "out_lvl_switch",
    "out_bin_switch"
  ] -- configured by Futurehome
}

Onboarding format

Constraints

All partners that want to receive data from Futurehome via HTTPS (with a few notable exceptions - i.e. Google) need to follow these onboarding guidelines

• Futurehome can batch events in HTTP requests, but no more than 150 events / batch. This can be configured during onboarding
• Futurehome will authorize the HTTP requests made to the partner's services using one of 2 methods:
  • Bearer token → token/api key is passed in the Authorization header with the value Bearer $token
  • Custom header name(configurable via onboarding) → token/api key is passed in the $headerName with the value $token
• Tokens can be obtained using the OAuth2 client_credentials flow (preferred) or, in exceptional cases where authentication cannot be done via an API, static tokens can be used
  • Client ID, client secret, scope and token endpoint will be configured during onboarding (obtained from the partner beforehand)
  • Token lifetime should be expressed in seconds as expires_in and be part of the access token response so Futurehome can fetch new tokens before they expire. Preferably, the service-to-service tokens will be valid for a longer period
  • Any error in the partner authentication request (fetching tokens) will mean stopping the partner worker, as requests can no longer be authorized
• Partners have a list of allowed services(FIMP) they can access that needs to be configured during onboarding time. For exceptions, there can be a * value that matches all services