Overview

Buildinglinks gateway v1

The gateway of the dataontvanger’s data plane: its apps call the data of other participants here, as if it were a local API, at /gateway/{alias}/… with an app key. The gateway adds the access token of the transfer and renews it when it is about to expire, signs every request for the provider (bl-request-signature), checks the provider’s signature over the answer (bl-response-signature), and records both as evidence. When the agreement requires signed requests (bl:signedRequests), an answer without a valid signature does not reach the app, and a write is on record before it leaves.

For a Buildinglinks dataset, the operations are those of the backend contract (backend.openapi.json) under /gateway/{alias}, within what the agreement covers: its buildings, and for part of a building only the named points (point_ids) without include. The provider’s status, body and Content-Type come back unchanged; the gateway passes on the request’s Content-Type, and no other headers. Bodies are limited to 16 MiB both ways. Errors of the gateway itself have a body of their own (GatewayError).

Information

License: Apache-2.0
OpenAPI version: 3.1.0

Authentication

appKey

A key of an app (Apps in the connector, POST /api/v1/apps/{id}/keys) with the scope gateway: Authorization: Bearer <key>. The app may use the connections and the access (reading, or also writing) it was given. In development also the break-glass token BL_ADMIN_TOKEN.

Security scheme type: http

appKeyHeader

The same app key in x-api-key, for clients that cannot set Authorization.

Security scheme type: apiKey

Header parameter name: x-api-key

controlPlane

A token of the participant’s own control plane, addressed to this gateway and used once: the connector reads its own connections with it (decisions #78).