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 (private home, STR, hotel, campus, locker), 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://openapp.house/api/v1'
export OPENAPP_API_KEY='https://openapp.house_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).

SDK

Python

devices = await client.devices.list()

TypeScript

import { AsyncClient } from "@tomers/openapp-sdk";

const client = new AsyncClient(apiKey, { org: orgId });
const devices = await client.listDevices(orgId);

Rust

use openapp_sdk::Client;

let client = Client::builder()
    .api_key("https://openapp.house_openapp_YOUR_SECRET")
    .build()?;

let devices = client.devices().list().await?;

Go

page, httpResp, err := client.DevicesAPI.ListDevices(ctx).
    XOrg(orgID).
    OutputOptions(*openapiclient.NewMultiResourceOutputOptionsQuery()).
    Pagination(openapiclient.PaginationQuery{
        Limit:  openapiclient.PtrInt32(50),
        Offset: openapiclient.PtrInt32(0),
    }).
    Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()
_ = page

Pass org context via client headers where required — see Organization context.

HTTP API (curl)

Prefer the SDK

Official SDKs handle authentication, base URLs, org headers, and typed request bodies — fewer moving parts than assembling raw HTTP. Use curl or JSON-over-HTTP when you need a minimal dependency, are generating a client from OpenAPI, or are proving connectivity before adding an SDK. See the SDK overview.

curl -sS "${OPENAPP_API_BASE}/devices" \
  -H "X-API-Key: ${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.

SDK

Python

await client.entities.actions(entity_id, "switchable.open")

TypeScript

const res = await fetch(
  `${apiBase}/entities/${entityId}/actions/switchable.open`,
  {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
      "content-type": "application/json",
      "x-org": orgId,
    },
    body: JSON.stringify({}),
  },
);
if (!res.ok) throw new Error(`open failed: ${res.status}`);

Rust

use openapp_sdk::Client;
use serde_json::json;

let client = Client::builder()
    .api_key("https://openapp.house_openapp_YOUR_SECRET")
    .build()?;

client
    .entities()
    .invoke_action(entity_id, "switchable.open", &json!({}))
    .await?;

Go

httpResp, err := client.EntitiesAPI.ExecuteEntityAction(ctx, entityID, "switchable.open").
    Body(map[string]interface{}{}).
    Execute()
if err != nil {
    return err
}
defer httpResp.Body.Close()

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

HTTP API (curl)

Prefer the SDK

Official SDKs handle authentication, base URLs, org headers, and typed request bodies — fewer moving parts than assembling raw HTTP. Use curl or JSON-over-HTTP when you need a minimal dependency, are generating a client from OpenAPI, or are proving connectivity before adding an SDK. See the SDK overview.

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

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; use dedicated scoped keys or agent credentials. A scoped credential reaches only the routes and roles in its scope and gets 403 everywhere else.
Agent reaches the wrong doors	Set the agent’s allowed_entity_ids; it is intersected with the key’s entity list. An agent with no list is not entity-restricted.
Unattended unlock	Set the agent’s confirmation mode (always or physical_only) so opens need a preview token; document org policy.
Door not classified	switchable.open and switchable.toggle return 409 (life_safety_class_required or life_safety_attestation_required) until the opening is classified and attested — see Life safety and egress.
Audit trail	Every switchable.* action is recorded as entity.action.succeeded or entity.action.denied, attributed to the agent, API key, or user. Pull it with the audit API, export it, or stream it to your endpoint with HMAC-signed webhooks — see Query access and audit activity.

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.