Build an agent that controls physical access

An access-control agent (or integration bot) calls OpenApp on behalf of an operator: list doors, open a gate when a parcel arrives, or revoke a guest invite at checkout. This guide covers the minimum wiring — credentials, org scope, and executing switchable.open safely.

For sector-specific workflows (hotels, campuses, STR), pair this with Integrate OpenApp with your existing software and Model by sector.

Prerequisites

1. An OpenApp account with permission to manage the target organization.
2. An API key for server-to-server use.
3. The organization id (ULID) and at least one entity id for a door or gate (from the dashboard or GET /entities).

Store secrets in environment variables — never embed keys in prompts, llms.txt, or public repos.

export OPENAPP_API_BASE='https://api.openapp.house/api/v1'
export OPENAPP_API_KEY='v1_openapp_YOUR_SECRET'
export OPENAPP_ORG_ID='01HORG00000000000000000000'
export ENTITY_ID='01HENTITY000000000000000000'

Organization context (X-Org)

Many routes are scoped to an organization. Pass the org id in the X-Org header when the API reference or Organization context docs say it is required (for example GET /devices, integration admin routes).

curl -sS "${OPENAPP_API_BASE}/devices" \
  -H "Authorization: Bearer ${OPENAPP_API_KEY}" \
  -H "X-Org: ${OPENAPP_ORG_ID}"

Execute a door action

Doors and relays use entity actions. The common unlock action is switchable.open — the same call as Open the door with the HTTP API.

curl -sS -X POST \
  -H "Authorization: Bearer ${OPENAPP_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Org: ${OPENAPP_ORG_ID}" \
  -d '{}' \
  "${OPENAPP_API_BASE}/entities/${ENTITY_ID}/actions/switchable.open"

Python (SDK)

import os
from openapp_sdk import AsyncClient

client = AsyncClient(os.environ["OPENAPP_API_KEY"])
await client.entities.by_id(os.environ["ENTITY_ID"]).open()

Pass org context on list calls via headers where required — see Entities and Organization context.

Discover entities before acting

Agents should list or resolve entities instead of hard-coding ids when possible:

1. GET /integrations → pick the Virtual Access or hardware integration.
2. GET /integrations/{id}/entities or GET /entities with pagination.
3. Match entity_type and metadata (door name, zone, external id).
4. Call POST /entities/{id}/actions/{action_id} only on the resolved id.

See Agent-relevant API index for operation groupings.

Safety checklist

Risk	Mitigation
Wrong door opened	Resolve entity by id + human-readable label; confirm in UI for first deploy.
Stale or stolen API key	Rotate keys in the dashboard; scope automation to dedicated keys.
Unattended unlock	Gate agent tools behind confirmation; document org policy.
Missing audit trail	Surface API errors to operators; use dashboard audit where available.

OpenApp orchestrates access; life-safety and compliance remain the operator’s responsibility — see Access control architecture.

Next steps

• Time-bound guest invitations for STR and hotel flows.
• Virtual intercom flow for directory + call + unlock.
• SDK overview to replace raw HTTP in production code.