Virtual Access

At a glance

Product: OpenApp Virtual Access
Manufacturer: OpenApp

Not for electrically locking a means of egress.OpenApp is ingress-only software. Occupants must be able to exit without this integration, the cloud, or a phone. SeeLife safety and egress.

Getting started

This provider does not expose integration-level actions or ops; instead, it uses devices with a kind field in their metadata to define directories, doors, and apartments. Door openers reference switch entities from other integrations (e.g. Shelly Cloud, MQTT).

Create an integration with provider type virtual_access and set the config. Door/light delay fields are optional overrides; if omitted, the backend uses the deploy-wide virtual access defaults.
Create a directory device with kind: "virtual_access_directory" in its metadata.
Create apartment entities under the directory device (entity_type apartment) and set their metadata. Manage them in the Virtual Intercom section (Access → building → Virtual Intercom).
Create portal devices with kind: "virtual_access_portal" in their metadata, link go2rtc cameras and opener entities.
Open the access dashboard to view cameras and open portals.

Device kinds

Kind	Purpose
`virtual_access_directory`	Building directory. Apartments are entities (entity_type `apartment`) under this device.
`virtual_access_portal`	A portal (door/gate/etc.) with cameras and optional openers

Directory device metadata

A virtual_access_directory device uses:

Field	Type	Description
`kind`	string	Must be `"virtual_access_directory"`

Apartments are modeled as entities under the directory device, not in device metadata. Create one entity per apartment with entity_type: "apartment" and set entity metadata (apartment_number, display_name, etc.).

Portal device metadata

A virtual_access_portal device uses the following metadata structure:

Field	Type	Description
`kind`	string	Must be `"virtual_access_portal"`
`go2rtc_camera_device_ids`	string[]	IDs of go2rtc camera devices for this portal
`virtual_access.openers`	object[]	Ordered list of opener entities. Each: `{ entity_id, label? }`. The dashboard tries each in sequence until one succeeds (fallback).
`virtual_access.open_config`	object	Optional. Controls the portal-level door auto-close behavior: `auto_close` (bool, default true), `auto_close_delay` (seconds, default = integration `default_door_auto_close_delay_seconds` when set, otherwise the deploy-wide backend default).
`virtual_access.lights`	object[]	Optional. Light fixtures to turn on when the door is opened (e.g. lobby light). Each: `{ entity_id, label?, auto_off_config? }`. Light auto-off uses `auto_close`/`auto_close_delay` in the nested config, defaulting to integration `default_light_auto_off_delay_seconds` when set, otherwise the deploy-wide backend default.
`virtual_access.life_safety_class`	string	Opening class required to open this portal. See Life safety and egress.
`virtual_access.life_safety_attestation`	object	Commissioning attestation (independent egress, power-fail behavior, installer name, …). Required to open access classes.

Example:

{
  "kind": "virtual_access_portal",
  "go2rtc_camera_device_ids": ["01HXXX...", "01HYYY..."],
  "virtual_access": {
    "openers": [
      { "entity_id": "01HZZZ...", "label": "Main Entrance" },
      { "entity_id": "01HAAA...", "label": "Backup Relay" }
    ],
    "open_config": {
      "auto_close": true,
      "auto_close_delay": 20
    },
    "lights": [
      { "entity_id": "01HBBB...", "label": "Lobby", "auto_off_config": { "auto_close": true, "auto_close_delay": 60 } }
    ]
  }
}

When a portal has openers, the access dashboard shows an Open button. Clicking it triggers switchable.open on the linked opener entities and optionally turns on configured lights.

Auto-close semantics

virtual_access.open_config describes the portal’s own door auto-close behavior.
If auto_close is omitted or true, OpenApp sends auto_off_seconds to the opener action using auto_close_delay, the integration’s default_door_auto_close_delay_seconds when set, or the deploy-wide backend default otherwise.
If auto_close is false, OpenApp sends no door auto-close payload, so the portal itself does not request an automatic close.
The dashboard’s Effective door auto-close value reflects this portal configuration, not fallback/default auto-off behavior of the linked opener integration.
Linked opener entities can still expose their own switchable auto-off status panel, which describes the opener device itself.
virtual_access.lights[*].auto_off_config is separate from the door config. Each light keeps its own effective auto-off behavior and status/fix alignment, and uses the integration’s default_light_auto_off_delay_seconds when set, or the deploy-wide backend default otherwise.

Automatic directory filling from photos

Use Enrich to fill the visitor directory (display_name on apartment entities) from photos of intercom panels or post office box banks. Visitors see these names in the public intercom directory (GET …/targets).

In-app flow (recommended)

Open Access → building → Virtual Intercom.
Click Enrich.
Upload one or more photos (camera or gallery). Photos are resized on your device before upload.
Click Analyze. OpenApp sends the images to Google (Gemini API) and returns structured apartment names.
Review the table (rename existing units or add new rows), edit names if needed, then Commit.

Requirements: entities:update permission; a directory device on the integration. In cloud zones, operators must set OPENAPP_GEMINI_API_KEY in AWS Secrets Manager (openapp/<workspace>/backend/gemini_api_key) and roll the backend service.

Privacy: OpenApp does not store uploaded photos. They are processed by Google for analysis only; see Google Gemini API privacy for provider terms.

Scope: Enrich updates display names (and can create apartment rows). It does not set floors, residents, or call routing.

Manual JSON fallback

If photo analysis is unavailable, expand Paste JSON manually in the Enrich modal and paste or upload JSON in the same shape as before ({ "apartments": [ … ] }). That path does not send images through OpenApp.

Setup reference

Config

Field	Type	Required	Description	Default	Example
location	object	optional	Building location. When set, must include lat, lng, and address (LocalizedString). Optional: city, country.	—	{ "lat": 32.0, "lng": 34.8, "address": { "en": "123 Main St" } }
default_door_auto_close_delay_seconds	integer	optional	Optional per-integration override for the door auto-close delay used when a portal enables auto-close without setting an explicit delay. If omitted, the backend uses the deploy-wide virtual access default.	—	20
default_light_auto_off_delay_seconds	integer	optional	Optional per-integration override for the light auto-off delay used when a linked light enables auto-off without setting an explicit delay. If omitted, the backend uses the deploy-wide virtual access default.	—	120
floor_order	array of strings	optional	Optional ordered list of canonical floor keys for this building (`n:{floor_number}` for numeric floors, or `l:{hex}` for label-only floors—same encoding as apartment metadata). Usually edited in Access → Building (drag-and-drop). Supplied to public directory sorting when set.	—	["n:-1", "n:0", "n:1", "l:a1b2c3d4e5f67890"]

Apartment entity metadata (per apartment entity under directory device)

Field	Type	Required	Description	Default	Example
apartment_number	integer	optional	Numeric apartment/unit when not using a custom label.	—	101
apartment_label	object	optional	Apartment's display identifier when using custom label.	—	{ "en": "Warehouse", "he": "מחסן" }
display_name	object	required	LocalizedString map: { [locale: string]: string }.	—	{ "en": "Apt 101", "he": "דירה 101" }
floor_number	integer	optional	Numeric floor when not using a custom label.	—	1
floor	object	optional	Floor's display name when using custom label (e.g. Ground, 1st, Lobby).	—	{ "en": "Ground", "he": "קומת קרקע" }
image_asset_id	string	optional	S3 media asset ID for apartment image. Set via image upload in the UI.	—	01HXXX...
virtual_access	object	optional	Per-apartment access policy overrides (policy or policy_overrides).	—	{ "policy": { "allowed_actions": ["call"] } }

Policies

Policies restrict access on top of roles — they never grant it. Browse the policy catalog for arguments and examples. Expand a category below to see the policies that apply to this integration, then expand a policy for details.

Invitations

Guest invites — duration, uses, who may create them, and which doors they can cover.

19 policies

Invitation curfew

Blocks invitation-based opens during a forbidden time window (for example nights).

Admins and residents are never curfewed; existing invitations are evaluated live, not modified.

Learn more — Invitation curfew

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — no hour restrictions on invitation-based access.
Enforcement: Enforce

Max invitation duration

Caps how long each invitation schedule slot may last.

Longer create or update requests are rejected, not shortened.

Learn more — Max invitation duration

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — no policy cap on invitation slot length.
Enforcement: Enforce

Max share duration

Caps how long a short-term share (TTL invitation) may last.

Combined with max invitation duration as the stricter of the two. Longer create requests are rejected, not shortened.

Learn more — Max share duration

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: System default is 86400 (1 day) when unset. Org policy may raise the share cap up to 31536000 (365d).
Enforcement: Enforce

Default share uses

When the author omits a use count on a share, store this default.

The system default is 1 when this policy is not configured.

Learn more — Default share uses

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — omitted share max_uses stores 1.
Enforcement: Enforce

Max share uses

Ceiling on how many times a share may be used.

Unlimited shares require allow_unlimited on every applicable row and no invitation_max_uses.

Learn more — Max share uses

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — no extra ceiling; unlimited shares remain forbidden.
Enforcement: Enforce

Max invitation uses

Requires a finite use count and rejects unlimited invitations or counts above the cap.

Learn more — Max invitation uses

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — unlimited-use invitations are allowed.
Enforcement: Enforce

Max invitation devices

Caps the number of unique guest browsers or app installations that may register an invitation.

Learn more — Max invitation devices

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — invitations may register any number of devices.
Enforcement: Enforce

Max active invitations per user

Caps how many enabled, unexpired invitations one person may have at once.

Learn more — Max active invitations per user

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — no cap on how many invitations one person may keep active.
Enforcement: Enforce

Require invitation expiry

Forbids open-ended recurring invitations that never end.

Learn more — Require invitation expiry

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — never-ending recurring invitations are allowed.
Enforcement: Enforce

Allowed entry kinds

Limits which portal types (door, gate, boom-gate) an invitation may grant.

Combination intersects allowed sets.

Learn more — Allowed entry kinds

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — any portal entry kind may be granted.
Enforcement: Enforce

Require invitation justification

Requires a non-empty creation justification when creating or updating an invitation.

Learn more — Require invitation justification

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — justification is optional.
Enforcement: Enforce

Max doors per invitation

Caps how many unique portals a single invitation may grant.

Learn more — Max doors per invitation

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — no policy cap on portals per invitation.
Enforcement: Enforce

Own-apartment doors only

Invitations may only grant doors the author can open as a resident of an allowed apartment.

Org/integration admins are exempt unless applies_to says otherwise. PalGate-only sites with no apartments fail for residents.

Learn more — Own-apartment doors only

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — invitations may grant any portal the author can otherwise share.
Enforcement: Enforce

Prohibit master-door invitations

Rejects an invitation if any granted portal’s door is a listed OpenApp device id (union of ids; never client-forged hardware ids).

Learn more — Prohibit master-door invitations

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — master doors may be granted on invitations.
Enforcement: Enforce

Who may invite

Literal allow-list of roles that may create invitations.

Combination intersects lists; empty intersection means nobody. Not admin-exempt. Compose with user_sharing (both must pass).

Learn more — Who may invite

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — anyone who can otherwise create invitations may do so.
Enforcement: Enforce

No invitation re-share

When the row binds the actor, invite create/update is rejected.

Org/integration default bind is resident (invitees), not generic members. Device-tier without applies_to binds everyone.

Learn more — No invitation re-share

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — invitees may create further invitations if their roles allow it.
Enforcement: Enforce

Require invitation identity

Requires a host PIN, a host-attached photo, and/or a verified invitee phone before an invitation can be created or used.

Learn more — Require invitation identity

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — PIN, photo, and verified phone are optional.
Enforcement: EnforceRequire approval

Invitation allowed days

Limits invitation-based opens to listed weekdays, minus blackout dates and optional holiday-calendar dates.

Existing invitations are evaluated live, not modified.

Learn more — Invitation allowed days

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — invitation-based access is not limited by weekday or blackout date.
Enforcement: Enforce

Holiday calendar

Lists organization-local ISO dates that invitation allowed-days can treat as holidays.

This type does not deny access by itself.

Learn more — Holiday calendar

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — no shared holiday date list.
Enforcement: Enforce

Holds

Door hold-open and hold-closed — who may set a hold and for how long.

5 policies

Require hold expiry

Members and residents cannot set a permanent hold.

Temporary (and unless also forbidden, weekly) holds are still allowed.

Learn more — Require hold expiry

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — permanent holds are allowed for anyone with the set-hold role.
Enforcement: Enforce

Max hold duration

Caps how long a temporary hold can last.

Longer requests are rejected, not shortened. PalGate hardware latch max is an extra cap when present.

Learn more — Max hold duration

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — no policy cap on temporary hold duration.
Enforcement: Enforce

No repeating holds

Members and residents may only set a one-shot hold, not a repeating calendar schedule.

Learn more — No repeating holds

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — repeating holds are allowed for anyone with set-hold.
Enforcement: Enforce

Allowed hold modes

Limits members and residents to hold-open, hold-closed, or both (for example, stay-off for lights but not stay-on).

Learn more — Allowed hold modes

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — both hold-open and hold-closed are allowed.
Enforcement: Enforce

No holds

Members and residents cannot set a hold, even if an admin granted the set-hold role.

Device-tier without applies_to binds everyone, including admins.

Learn more — No holds

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — anyone with the set-hold role may set a hold.
Enforcement: Enforce

Sharing

Who may share access or manage linked users outside invitations.

3 policies

User sharing control

Restricts whether non-admins may share access or create invitations out of band — block outright or require admin approval.

Learn more — User sharing control

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — non-admins may share access freely.
Enforcement: EnforceRequire approval

No transitive delegation

Invite create: org admin or apartment admin only.

Vendor users_admin writes (except list): org admin only. Runs in addition to user_sharing.

Learn more — No transitive delegation

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — ordinary role and user_sharing rules apply.
Enforcement: Enforce

Approval threshold

Requires N distinct organization-admin approve votes before a pending policy approval proceeds.

Any deny denies. Self-approval does not count.

Learn more — Approval threshold

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — a single admin approve or deny is enough.
Enforcement: Enforce

Lifecycle

Move-out and idle membership — revoke leftover invites without deleting the user.

2 policies

Revoke invites on move-out

When a resident is removed from an apartment, enabled invitations they authored that grant that apartment’s doors are revoked.

Learn more — Revoke invites on move-out

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — leftover invitations stay enabled after move-out.
Enforcement: Enforce

Expire dormant users

After idle days, revoke that person’s invitations and remove residencies.

The user account is not deleted. Admins are exempt unless included.

Learn more — Expire dormant users

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — idle members and residents are not auto-expired.
Enforcement: Enforce

Agent safety

Time windows, throttles, and extra confirmation for agents, API keys, and guests.

4 policies

Quiet hours

Blocks access during a local hour window for listed principal kinds (agents, API keys, invitations).

Admins are not restricted unless included.

Learn more — Quiet hours

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — no quiet-hours window.
Enforcement: Enforce

Rate limit

Throttles entity opens per principal in a sliding window so retrying agents cannot exhaust door quota.

Learn more — Rate limit

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — no policy throttle on opens.
Enforcement: Enforce

Require step-up

Requires extra confirmation before a physical write for the listed principal kinds.

Learn more — Require step-up

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — no extra confirmation beyond ordinary authorization.
Enforcement: Enforce

Anti-tailgating cooldown

After a successful open of an entity, further opens of that entity are denied until the cooldown elapses.

Admins are exempt by default.

Learn more — Anti-tailgating cooldown

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — no per-door cooldown after a successful open.
Enforcement: Enforce

Operational

Site-wide lockdown and notifications when a policy denies access.

6 policies

Emergency lockdown

When active, denies non-admin inbound cloud opens.

Does not lock a means of egress or fire-door assembly, and is not a building lock-in.

Learn more — Emergency lockdown

Enforced at: Access-time
Tiers: Org
Default: Not configured — no lockdown.
Enforcement: Enforce

Emergency free egress

When active, OpenApp will not deny inbound cloud opens.

This is not fire-alarm release.

Learn more — Emergency free egress

Enforced at: Access-time
Tiers: Org
Default: Not configured — ordinary denies still apply.
Enforcement: Enforce

Notify on curfew attempt

Emits an audit event (and configured channels) when curfew blocks an open.

Learn more — Notify on curfew attempt

Enforced at: Denial hook
Tiers: OrgIntegration
Default: Not configured — curfew denials are not additionally notified.
Enforcement: Enforce

Maintenance window

During a local hour window, only listed roles may open.

Empty role intersection means nobody. Technicians match the same way as who-may-invite.

Learn more — Maintenance window

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — no technician-only maintenance window.
Enforcement: Enforce

Notify on first use

Emits an audit event when an invitation’s use count goes from 0 to 1, if audit is among the channels.

Learn more — Notify on first use

Enforced at: Access-time
Tiers: OrgIntegration
Default: Not configured — first invitation use is not additionally notified.
Enforcement: Enforce

Notify on new sharing

Emits an audit event after users_admin writes (except list) and after invitation create that actually shares, if audit is among the channels.

Learn more — Notify on new sharing

Enforced at: Authoring-time
Tiers: OrgIntegration
Default: Not configured — new sharing is not additionally notified.
Enforcement: Enforce