Getting Started

This guide covers what must be in place before your tenant app can fetch and connect to a user's smart spaces, and how to call the Service Connection API.

Prerequisites

Before your application can connect to Fentrica smart spaces, the following must be in place:

1. User Sync & Credentials — Fentrica integrates with your API to sync your users, then issues your credentials (or binds your own identity provider via JWKS). The integration is provisioned as a service connection, and each site receives its own serviceConnectionId. See Authentication.
2. Authenticate — Your users sign in with Fentrica auth web components or your own identity provider (JWKS) and obtain a JWT. Every token is verified in both the Fentrica cloud and the edge device.
3. Fetch Units & Devices — Use the Service Connection API to retrieve the smart space units and devices your user has access to.
4. Connect to Devices — Establish real-time WebSocket connections to each device using the @larva.io/clouddevice library.
5. Render UI Components — Load and render device controls using @larva.io/webcomponents in your React, Vue, or vanilla JS application.

Service Connection API

Once authentication and service connection are configured, your application can fetch the units and devices assigned to the authenticated user.

Server

The API is available at:

https://api.building.fentrica.com/orgs

The /orgs path prefix identifies the Organizations microservice — all service connection endpoints are served from this microservice.

Endpoint

GET https://api.building.fentrica.com/orgs/orgs/:orgId/services/connections/:serviceConnectionExternalId/access-policies/:accessPolicyExternalId/views/units-devices

Identifying the user's access

This endpoint takes two external identifiers — and both are yours, not new ids you have to track.

• serviceConnectionExternalId identifies the site's integration. Each site the integration covers has its own, provisioned during setup.
• accessPolicyExternalId is your own identifier for what a user is allowed to access — a booking id, a rental agreement id, a membership id: whatever your system already uses. You agree this mapping with Fentrica once, during user-sync setup, so your app never learns a new identifier.

Your app already knows the user's booking or agreement id, so it simply passes that id. Fentrica resolves it to exactly the smart spaces and devices that booking or agreement grants — this room, these devices, for the length of this stay — and nothing more. When the booking ends, so does the access.

CORS Policy

The API is protected with CORS. During development, requests are allowed from:

• capacitor:// — Capacitor native app shell
• http://localhost:8080 — local development server

Any custom domain or cloud-hosted application must be whitelisted by our support team before it can make API requests. Contact support to register your origin.

Authentication

Requests must include a valid tenant JWT token. See Authentication for how tokens are issued and verified.

Path Parameters

Response

Returns the smart spaces (units) and their devices that this access policy — the user's synced booking or agreement — grants access to:

[
  {
    "id": "unit-uuid",
    "name": "Apartment 301",
    "devices": [
      {
        "id": "device-uuid",
        "serialNumber": "FEN-A1B2C3"
      }
    ]
  },
  {
    "id": "unit-uuid-2",
    "name": "Apartment 302",
    "devices": [
      {
        "id": "device-uuid-2",
        "serialNumber": "FEN-D4E5F6"
      }
    ]
  }
]

Each unit represents a smart space, and each device is a Fentrica edge device (controller) that your application connects to for real-time control.

Next Steps

• Cloud Device Connection — Connect to devices via WebSocket
• Web Components — Render device controls in your app