Resource hierarchy (data model)

View full API reference

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

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).

Users

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

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).

Devices

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

Entities

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

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).

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.