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, on a membership change or background sweep (lifecycle), or after a denial (record 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

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 — a single admin approve or deny is enough.

Raises the approval inbox above a single admin click. Pending approvals come from user_sharing rows in approval_required mode. Scope is org_admins: only distinct principals with policies:update in the organization may vote. Combination takes the maximum count. Any deny vote denies the request. The requester cannot vote on their own request (403), and a second vote from the same principal returns 409.

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. 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
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.

How overlapping rows combine

Most-restrictive: maximum of count across applicable rows at the org, integration, and device tiers. Disabled 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 vote on their own request.

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 come from distinct principals holding policies:update in the organization. The requester cannot vote on their own request (403), and a second vote from the same principal returns 409. 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 enabled approval_threshold rows at the organization, integration, and physical-device tiers. Disabled 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"
  },
  "enforcement": "enforce"
}

count must be a positive integer and scope must be org_admins; other scope values are rejected. output and applies_to are not supported and are rejected. The generated OpenAPI document exposes this shape as ApprovalThresholdPolicyConfig.