Approval threshold

Type

approval_threshold

Category

Sharing

Enforced atWhen this policy is checked: while someone tries to open, while they create or change an invitation or hold, or after a denial (notify only).

Authoring-time

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

OrgIntegrationDevice

EnforcementHow a configured row behaves. Enforce blocks. Require approval opens an admin inbox when the type supports it. Audit only records and never blocks.

Enforce

DefaultWhat happens when no row of this type is configured.

Not configured — a single admin approve or deny is enough.

Raises the approval inbox above a single admin click. Scope is org_admins: only distinct organization admins count. Combination takes the maximum count. Any deny vote denies the request. The requester approving their own request does not count toward N.

When it is enforced

Evaluated when someone creates or updates an invitation, hold, or share. Requests that would exceed the limit are rejected — they are not silently rewritten.

Where to set it

Settings → Policies (org), the integration Policies tab, or — on PalGate — the device steward Policies tab.

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

Arguments

The config object on create/update. Shared row fieldsenforcement (enforce, require_approval,audit_only) and enabled apply to every type;audit_only and disabled rows never block.

Name	Type	Required	Values	Description
count	integer	Yes	—	Number of distinct org-admin approve votes required. Must be greater than 0.
scope	string	Yes	org_admins	Who may vote. Only org_admins is accepted.
output	string or integer	No	—	Optional channel or output id. When set, the policy binds only that output. When omitted, it binds every output of the tier target. A scoped row does not apply when the acting output is unknown.

How overlapping rows combine

Most-restrictive: maximum of count across applicable rows. Disabled and audit_only rows never raise the threshold.

Example

A pending share needs two different org admins to approve. One admin deny closes the request. The author cannot satisfy the count by approving themselves.

config

{
  "count": 2,
  "scope": "org_admins"
}

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
• User sharing control (user_sharing)
• Who may invite (invite_creator_roles)
• Notify on new sharing (notify_on_new_sharing)

Approval API contract

For a pending request, use the org-scoped approval endpoints:

• GET /orgs/{org_id}/policy-approvals lists approve_count and the effective required_count.
• POST /orgs/{org_id}/policy-approvals/{id}/approve records one approve vote.
• POST /orgs/{org_id}/policy-approvals/{id}/deny records a deny and closes the request immediately.

Votes are distinct authenticated organization-admin votes. The requester cannot approve their own request, and submitting a second vote from the same principal returns a conflict. An approval remains pending until required_count is reached; then it becomes approved. Any deny is terminal for that request.

The effective threshold is the maximum positive config.count across applicable enforcing approval_threshold rows at the organization, integration, and physical-device tiers. Disabled and audit_only rows do not contribute. The configuration is therefore evaluated when the approval list or decision endpoint loads the request context rather than copied into the request at creation time.

The public write shape is:

{
  "policy_type": "approval_threshold",
  "config": {
    "count": 2,
    "scope": "org_admins",
    "output": "main"
  },
  "enforcement": "enforce"
}

count must be a positive integer and scope must be org_admins; other scope values are rejected. output is optional and accepts a provider-derived channel or output id (string or integer). The generated OpenAPI document exposes this shape as ApprovalThresholdPolicyConfig.