Resource hierarchy (data model)

View full API reference

This page explains the core OpenApp resource hierarchy and how the main objects relate.

How the pieces fit together

Read these ideas first, then use the diagram in the next section as a compact map.

1. Tenant boundary — Work is scoped to an organization (org): ownership, membership, and (where applicable) billing. Orgs can be hierarchical when you need a parent tenant with child sites or customers.

2. Who can do what — A user is a provisioned identity (for example name and email). Roles attach to membership in that org and decide what that person may do in the dashboard and APIs.

3. Connected systems and what you control — The org configures integrations (a provider connection such as Home Assistant, KNX, or Shelly; see Integrations below). Each integration owns devices and zones (spaces such as rooms or floors, often imported from the provider). A device exposes entities—relays, lights, sensors, and similar—which can be placed in a zone when you want structure for navigation or access rules.

High-level map

flowchart TD
  Organization --> Integration
  Organization --> User
  User --> Role
  Integration --> Zone
  Integration --> Device
  Device --> Entity
  Zone --> Entity

Organizations (orgs)

An organization is a tenant boundary and ownership container. Orgs can be hierarchical (an org can have a parent org).

See the resource reference:

• Organizations

Users

A user represents a provisioned identity (name + email).

See the resource reference:

• Users

Roles

A role is a validated string (for example integrations:read) that grants permissions within the context of an org.

See the full list of roles:

• Roles

Integrations

An integration is a configured provider connection owned by an org (for example Home Assistant, KNX, Shelly Cloud).

See the integrations catalog (per-provider setup and options):

• Integrations

Devices

A device is a physical or virtual device that belongs to an org and is owned by a specific integration instance.

See the resource reference:

• Devices

Entities

An entity is the controllable “thing” on a device (for example a specific relay channel, light, or sensor).

See the resource reference:

• Entities

Zones

A zone is a logical/physical space (supports parent-child hierarchy) that belongs to an integration (for example rooms imported from Home Assistant, or a KNX building structure).

See the resource reference:

• Zones

Common patterns

• Ownership:
  • Orgs own integrations and devices.
  • Integrations own zones and devices.
  • Devices own entities.
  • Zones optionally “contain” entities (an entity may be assigned to a zone).
• Provider mapping:
  • external_id typically maps an OpenApp object to its upstream provider’s identifier.
  • Provider-specific extra fields usually live in provider-scoped configuration and metadata.

See also

• Reference overview — one page per resource type (orgs, users, roles, devices, entities, zones) with links into the HTTP API reference.