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 from the integrations catalog; see Integrations below). Each integration owns devices. A device exposes entities—relays, lights, sensors, and similar.

4. Physical space — The org owns zones: buildings, floors, and rooms in a tree. One zone holds devices and entities from any integration. A device has a zone, and its entities inherit it unless an entity is placed somewhere else.

High-level map

flowchart TD
  Organization --> Integration
  Organization --> User
  User --> Role
  Organization --> Zone
  Integration --> Device
  Device --> Entity
  Zone --> Zone
  Organization --> WifiNetwork
  WifiNetwork -. offered in .-> Zone
  Zone -. placement .-> Device
  Zone -. placement .-> 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 (see the integrations catalog for supported providers).

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 physical space—a building, floor, or room—that belongs to the org, not to an integration. Zones nest through parent_zone_id inside one org. Zones imported from a provider (for example Home Assistant areas) keep that provenance as provider links; one zone can link to several providers, and deleting an integration removes only its links.

Devices have an optional zone_id. Entities inherit the device zone, set their own, or opt out (zone.mode: inherit, explicit, or none).

See the resource reference:

• Zones

Wi-Fi networks

A Wi-Fi network belongs to the org and is shared with the people invited to doors, for doors where there’s no cellular reception. A network is linked to any number of zones, and a door offers the networks on its zone and on every zone above it. Passwords are stored in a secrets store, not in the database, and are returned only to callers who can update zones.

See the task guide:

• Wi-Fi for doors without signal

Common patterns

• Ownership:
  • Orgs own integrations and devices.
  • Orgs own zones.
  • Orgs own Wi-Fi networks; each links to zones.
  • Integrations own devices.
  • Devices own entities.
  • Zones place devices and entities; an entity’s effective zone is its own or its device’s.
• Provider mapping:
  • external_id typically maps an OpenApp device or entity to its upstream provider’s identifier. Zones use provider_links (integration_id, external_id) instead, because one zone can map to several providers.
  • 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.