Require step-up

Type

require_step_up

Category

Agent safety

Enforced atWhen this policy is checked: while someone tries to open, while they create or change an invitation or hold, on a membership change or background sweep (lifecycle), or after a denial (record only).

Access-time

TiersWhere an admin can set this policy: the whole organization, one integration, or the physical device when the connector supports a device steward.

OrgIntegration

EnforcementEnforcement modes this type accepts. Enforce applies the row. Require approval (user sharing only) opens an admin approval inbox instead of blocking.

Enforce

DefaultWhat happens when no row of this type is configured.

Not configured — no extra confirmation beyond ordinary authorization.

Requires an extra confirmation step before a physical write (for example opening a door) for the listed principal kinds. Human admins are not included unless applies_to says so. A caller is every kind it is at once, and a row binds when any of them is listed. Use this so an agent or API key cannot move hardware on a single unattended call. Evaluated on the entity-action API.

When it is enforced

Evaluated when someone opens a door or gate or triggers an entity action. If this policy applies, the open is denied even when roles and grants would otherwise allow it.

Where to set it

Settings → Policies (org) or the integration Policies tab.

Policies never grant access. See thepolicies architecture guidefor how org, integration, and device tiers combine.

Arguments

The config object on create/update. Row fields outsideconfig are enforcement (this type acceptsenforce; any other value is rejected with 400), enabled (disabled rows never apply), and capability.

Name	Type	Required	Values	Description
resource_selector	string or string[]	No	—	Which entities need step-up: `*` (or omitted) for every entity, one entity ULID, or a non-empty array of entity ULIDs. Any other value is rejected.
applies_to	string[]	No	agentapi_keyinvitationmemberresidentadminall	Principal kinds this row binds, as a non-empty array of agent, api_key, invitation, member, resident, admin, all. Other kinds, a bare string, and empty arrays are rejected. `all` matches every kind this policy can bind. A caller is every kind it is at once, and a row binds when any of them is listed. When omitted, the default applies. Default: agent, api_key, invitation

How overlapping rows combine

Boolean OR across applicable enforcing rows (any require-step-up wins).

Example

An API key must send the extra confirmation header before switchable.open succeeds. A resident opening from the portal is unaffected.

config

{
  "applies_to": [
    "agent",
    "api_key"
  ]
}

Integrations

This type is documented on these connectors:

• Home Assistant (home_assistant)
• KNX (knx)
• MQTT (mqtt)
• PalGate Cloud (palgate_cloud)
• Shelly Cloud (shelly_cloud)
• Shelly Websocket (shelly_websocket)
• Tasmota (tasmota)
• Virtual Access (virtual_access)
• Virtual Demo Devices (virtual_demo)
• Waveshare (waveshare)

Related

• Policy catalog
• Policies architecture guide
• Rate limit (rate_limit)
• Quiet hours (quiet_hours)
• Emergency lockdown (emergency_lockdown)

Typed configuration

The generated OpenAPI document exposes the config object as RequireStepUpPolicyConfig. applies_to is a non-empty array of principal kinds; a bare string, unknown kinds, and an empty array are rejected. Omit it to use the default set (agent, api_key, invitation).

resource_selector limits step-up to specific entities: "*" (the default) for every entity, one entity ULID, or a non-empty array of entity ULIDs. Any other value is rejected.

{
  "applies_to": ["agent", "api_key"],
  "resource_selector": ["01J9Z2W4Y8B3KQ5M7N6P0R1S2T"]
}

output is not supported and is rejected.

Confirmation protocol

require_step_up currently uses the authenticated preview-confirmation protocol. It is an additional confirmation of the exact write request, not an independent second factor or a replacement for MFA.

1. Call POST /entities/{id}/actions/{action_id}/preview with the exact JSON payload that will be executed.
2. If confirmation is required, the response includes preview_token.
3. Repeat the same request at POST /entities/{id}/actions/{action_id} with the token in X-OpenApp-Confirm.

The token is short-lived (10 minutes), single-use, and bound to the organization, authenticated principal, entity, action id, and exact JSON payload. A missing, expired, replayed, cross-principal, cross-entity, cross-action, or payload-mismatched token is rejected. A boolean header or a random ULID is not a valid proof. The preview does not call the hardware provider; the execute request is the only call that performs the physical write.

The proof is issued only after ordinary authentication and authorization succeed. Deployments that require a separate second factor must enforce that requirement in their authentication or credential layer; this policy does not claim to provide MFA.