门禁与大门控制

Acts on Door & Gate Access doors now: unlock, Lock now and Resume schedule, block or restore all access, beep to locate, and reboot a controller. Get doorIds from door_access_doors_read list; never guess them. Workflow steps and Agent devices need 'Workflows can open doors and change access' turned on (door_access_settings_read workflow_control); people in AI chat confirm instead.

Actions:

• unlock: Unlock doors. Unlocks now as an admin, past Access Policies, time windows, Block all access and force-closed maintenance; each door relocks after its hold time. Every door gets an Access Logs row with the reason and who did it. Pass doorId, doorIds, scopeIds or allDoors; with one door, data has its commandId, eventId and holdTimeSeconds. Needs reason. Asks for confirmation.
• pause_schedule: Lock now. Locks doors their auto-unlock schedule is holding open, until the schedule's current unlock period ends or Resume schedule. Doors without an auto-unlock schedule are skipped; a controller that is offline or needs a software update is reported.
• resume_schedule: Resume schedule. Hands doors back to their auto-unlock schedule after Lock now. A door inside an unlock period unlocks straight away. Doors without an auto-unlock schedule are skipped, and so are doors a duress lockdown holds (the result says so); they resume when the lockdown is lifted. Asks for confirmation.
• block_access: Block all access. Turns on Block all access: nobody gets in with the app or an integration until access is restored, whatever their Access Policies, grants or time windows. Admin unlocks and auto-unlock schedules still work. Doors already blocked are skipped. Asks for confirmation.
• restore_access: Restore access. Turns Block all access off again, so people's Access Policies, grants and time windows apply. Doors a duress lockdown holds stay blocked until the lockdown is lifted, and the result says so; doors that aren't blocked are skipped. Asks for confirmation.
• identify: Beep to locate a door. Plays about 2 seconds of beeps on the controller so someone on site can find it. No Access Logs row. Needs doorId.
• restart: Reboot a door controller. Reboots one door's controller, for example when it stopped responding. The door can't be opened from the app until it's back online. Only from AI chat, never from a workflow or Agent device. Needs doorId. Asks for confirmation.

Door controllers at a facility in Door & Gate Access, the doors and gates people open with the app. Use list to find a doorId and see which doors are online, in maintenance or blocked, and which rules, geofence and Access Policies apply; device_status to troubleshoot one controller; auto_unlock_preview to see when a schedule holds a door open. Adding or removing controllers is done in Device Management.

Actions:

• list: List doors. Each door with online state, maintenanceMode, blockAllAccess, Access Scope groupIds, overrides, effective rules and time-window access, Access Policies, auto-unlock schedule (with scheduledUnlockActive and scheduledUnlockPaused for Lock now) and device settings.
• auto_unlock_preview: Preview an auto-unlock schedule. Day by day, when the door's auto-unlock schedule holds it open, using the facility's current staffed and holiday hours. Pass schedule to preview a change before saving it with door_access_doors_write configure. Needs doorId.
• device_status: Door device status. Telemetry for one controller: update status, IP and network, Wi-Fi SSID, hardware, OS and app versions, uptime, CPU and memory. deviceStatus is null when it has reported none. Needs doorId.

更改 Door & Gate Access 门的安全、地理围栏和设备设置。谁可以解锁由 Access Policies (door_access_settings_write) 设置，而不是在这里。先使用 door_access_doors_read list 读取该门。

操作：

• configure：配置门。只有传入的字段会更改；null 表示清除。设备设置会立即推送到控制器，更改 autoUnlockSchedule 会使控制器上的门控制短暂重启。保持门常开或封锁门前会先询问。需要 doorId。可能需要确认。

Access Logs from Door & Gate Access at a facility, newest first: who tried which door, when, how (app, integration, admin unlock, workflow, AI Agent or duress alarm) and whether it worked. Use it to answer who opened a door, why someone was denied, what a workflow did, or to audit admin unlocks.

Actions:

• door_events: Door events. Each attempt with doorId, outcome, via, the person (userId, or personName for integration unlocks), actor (who sent an admin unlock, Lock now or Resume schedule, by name), the reason code for denials and failures, the note an admin unlock gave, and why access was allowed. Filters narrow the page; a sparse filter can return fewer rows with a nextCursor to read further back.
• no_visit_recorded: Windows with no visit. Access windows that ended across the facility without a successful unlock by the person they were for, such as a missed appointment, booking or visit. Covers one-time windows given to a person, from an admin or an integration; weekly windows and Access Policy schedules aren't included.

A facility's Door & Gate Access Settings: Access Policies (who may open which doors, and when) and their reach, why a person can or can't get in, Access Scopes (named door groups), app and geofence rules, automated app messages, setup progress and whether workflows can open doors. Change them with door_access_settings_write; sync settings are in door_access_sync_read.

Actions:

• rules: App and geofence rules. The settings document: geofence, accessTimeWindowGrace (early and late minutes on every window), appLock, supportContacts and the facility appMessage.
• policies: Access Policies. The versioned Access Policies document: each policy has an audience (a rule over person fields, holds and balances, or legacy member types and tags), targets (doors and scopes) and a schedule: anytime, scheduled windows, or the facility's staffed hours (facilityHours). blockRules keep matching people out at their doors whatever lets them in. Keep its revision for writes.
• policy_impact: Access Policy impact. How many people and doors one policy reaches now, and how many its age, hold and balance conditions keep out (excluded: age, membershipHold, accountBalance); check before editing or deleting it. Needs policyId.
• policy_impacts: Reach of every Access Policy. How many people and doors each Access Policy reaches now, counted as if it were on, and how many its age, hold and balance conditions keep out (excluded). A policy that reaches nobody or no doors is worth a look.
• block_rule_impacts: Reach of every block rule. For each saved block rule, counted as if it were on: its doors, how many people have a way in it closes there (withAccess), how many it keeps out now (blocked), and how many it would keep out with no hold or balance in force (blockedPermanently).
• explain_access: Why can or can't someone get in?. Runs the real access check for one person at one door (or every door), now or at at, and explains it: the decision, each block rule's match and each policy's rule with the person's value and pass, fail or unknown on every condition, and each policy's schedule now and next. draft tries an unsaved change first. Changes nothing. Needs userId.
• onboarding: Setup progress. Whether the facility has its first door and first person (activated, with when it happened), and which optional setup steps were reviewed: accessRules, sync and geofence.
• test_geofence: Test the geofence. Whether an unlock at this position would pass the facility (or one door) geofence. Changes nothing. Needs lat, lng.
• scopes: Access Scopes. Named sets of doors that policies target and grants name, with doorIds and geofence override. A door can be in several.
• scope: Get an Access Scope. Needs groupId.
• auto_messages: Automated app messages. Rules that set a person's app message from their membershipStatus, type, tag, doorVisibility (none or some), accountBalance (owing, or blocked by a policy's balance condition) or membershipHold (held: a hold period is in force; blocked: a policy's hold condition keeps them out). Manual messages and decoupled or suppressed people are never overwritten.
• auto_messages_sweep_status: Automated message sweep. Progress of the re-evaluation that runs after the messages change: status queued, running, done or error, with users scanned and updated. sweep is null before the first one.
• workflow_control: Can workflows open doors?. Whether 'Workflows can open doors and change access' is on. While it's off, workflow steps and Agent devices can't open doors, Lock now, Resume schedule, block or restore access, or change people's access; people in AI chat still can, after confirming.

Changes a facility's Door & Gate Access Settings: Access Policies, Access Scopes, app and geofence rules, automated app messages and setup steps. Read the current state with door_access_settings_read first; policy writes need its revision and return 409 when someone else changed them since.

Actions:

• update_rules: Save app and geofence rules. Send back the whole document from door_access_settings_read rules with your changes. Authorization fields are kept server-side; change access with Access Policies. Needs rules.
• update_policies: Replace all Access Policies. Atomically replaces the whole document, block rules included; prefer the single-policy actions, which keep block rules as they are. Needs accessPolicyConfig. Asks for confirmation.
• create_policy: Add an Access Policy. Needs policy, revision.
• update_policy: Edit an Access Policy. Replaces one policy; the others are untouched. Needs policyId, policy, revision.
• duplicate_policy: Duplicate an Access Policy. Needs policyId, revision.
• delete_policy: Delete an Access Policy. Needs policyId, revision. Asks for confirmation.
• create_scope: Add an Access Scope. Needs name.
• update_scope: Edit an Access Scope. Only the fields you pass change. Changing doorIds changes who can open those doors: check door_access_settings_read policy_impact first. Needs groupId.
• delete_scope: Delete an Access Scope. Needs groupId. Asks for confirmation.
• update_auto_messages: Save automated app messages. Full replace of the config from door_access_settings_read auto_messages. Queues a background re-evaluation of everyone at the facility; follow it with auto_messages_sweep_status. Needs config.
• preview_policy_migration: Preview moving to Access Policies. The Access Policies the facility's legacy rules would become, without saving, with sourceRevision and sourceFingerprint for commit_policy_migration.
• commit_policy_migration: Move to Access Policies. Saves the previewed policies so they decide access from now on. 409 access_policy_migration_stale when the rules or doors changed since the preview. Needs expectedRevision, sourceFingerprint. Asks for confirmation.
• update_onboarding: Tick off setup steps. Marks optional setup steps as reviewed (true) or not (false): accessRules, sync and geofence. Only the steps you pass change; returns the setup progress. Needs optional.
• update_workflow_control: Let workflows open doors. Turns 'Workflows can open doors and change access' on or off. While on, workflow steps and Agent devices can open doors, Lock now, Resume schedule, block and restore access, and add people or change their access. Only a person can change it. Needs enabled. Asks for confirmation.

How a facility fills User Access automatically: from integrations (source partner, such as booking, membership or HR systems), CCTV and your organisation's staff. Use it to see the sync settings, why a person did or did not sync, and what a bulk delete of synced people would remove. Change sync with door_access_sync_write.

Actions:

• partners: Integrations. Each integration (partnerId) with enabled state, synced people count and its time-window mapping.
• config: Sync settings. Per source: partner (with per-integration timeWindowAccess mappings and freshness), cctv, staff (on by default; which roles count is set in Org Settings > Brands > Door access), appInvitations rules, conflictResolution and the schedule.
• log: Sync log. Recent outcomes, newest first, with the reason each person did or did not sync and startedBy: a person, a workflow (with workflowId and name) or automatic.
• bulk_delete_preview: Preview deleting synced people. How many people synced from integrations door_access_sync_write bulk_delete would remove, a sample, and the confirmToken it needs. Changes nothing.

Changes how a facility syncs User Access from integrations, CCTV and your organisation's staff, runs a sync now, adds back the staff Access Policy, and bulk-deletes people synced from integrations. Read door_access_sync_read config first and keep unrelated settings.

Actions:

• update_config: Change sync settings. Merges your patch into the current settings. Turning staff sync off asks first. Needs config. May ask for confirmation.
• run: Sync now. Sweeps every enabled source (it also runs nightly) and returns processed, created, updated and skipped per source. Removals from an integration that look like a bad pull are held back as partner.removalGuardTripped; applying them with confirmMassRemoval asks first, and workflows never apply them. May ask for confirmation.
• create_staff_policy: Add back the staff Access Policy. Re-creates the Access Policy that gives your organisation's staff access, for example after someone deleted it. 409 too_many_access_policies when the facility already has the most it can have. Asks for confirmation.
• bulk_delete: Delete synced people. Soft-deletes the people synced from integrations listed by bulk_delete_preview. 409 when they changed since. Needs confirmToken. Asks for confirmation.

The people who can use the Door & Gate Access app at a facility (User Access): people added by hand, from integrations, from CCTV, and staff. Use it to find a userId, check whether and why someone can get in, or pick who to invite. Change people with door_access_users_write.

Actions:

• list: List people. Compact rows, sorted by name unless you pick another sort: hasAccess (a policy, grant or time window lets them in now or later) and which policies, the access switch, tags, sync, app use, balance (amountOwed in cents, balanceBlocked) and hold (membershipHold in force, holdBlocked). No phones or birth dates; get has the full row, find looks someone up by email, phone or member number.
• find: Find a person. The people at the facility with this email, mobile phone or the membership, customer or employee number an integration gave them; pass one. found and userId (the first match) make it easy to use in a workflow, for example to look up the person a form or booking names.
• get: Get a person. One row in full: phone, age (null without a birth date), the synced accountBalance and its exemption (accountBalanceExemptionActive), synced membershipHolds and the activeMembershipHold, balanceExcludedPolicyIds and holdExcludedPolicyIds (policies a balance or hold condition keeps them out of now), grants, admin timeWindowGrants, synced sourceTimeWindows and their freshness. Needs userId.
• effective_access: Explain a person's access. Per door: allowedNow, allowedVia or deniedReason, block and maintenance state, active and next time window, scopes and source freshness. Check this before replacing grants. Needs userId.
• people_config: Person types, statuses, tags and rule fields. The distinct person types, membership statuses and tags at the facility, plus fields: every field an Access Policy rule can match (including integration attributes.), its kind, how many people have data for it, and the values for pickers. Use it before writing audience.rule.
• invitation_preview: Preview app invitations. Who an invitation round would email, without sending: people with an email who have never used the app, by default only those with access who weren't invited yet. Returns counts, a sample and every userId for door_access_users_write send_invitation.

Adds, edits and removes the people who can use the Door & Gate Access app at a facility, and manages their grants, time windows, tags, app message, sync, app sessions and invitations. Find userIds and check current access with door_access_users_read first. Staff follow your organisation's user list: delete, decouple and recouple return 409 staff_row_managed. Workflow steps and Agent devices need 'Workflows can open doors and change access' turned on.

Actions:

• create: Add a person. Adds a person by hand. sendInvite also emails the app invitation. A phone or email already at the facility returns 409 with the existing row, unless matchExisting finds a person added by hand with the same email, which is returned with matchedExisting. Needs user.
• bulk_create: Import people. Up to 200 rows with per-row outcomes. Rows take the user fields plus accessEnabled and permanent grants; add time windows afterwards with set_time_window_grants. Emailing invitations asks first. Needs users. May ask for confirmation.
• update: Edit a person. Partial edit: accessEnabled (their access switch), the app message (appMessage { enabled, title, text, severity info|warning|critical }, null clears), autoMessageSuppressed, the balance exemption (accountBalanceExempt), admin timeWindowGrants and other fields. addTags and removeTags change their custom tags; tags from an integration or staff stay. Needs userId.
• delete: Remove a person. Soft delete; they lose app access and their access logs are kept. Needs userId. Asks for confirmation.
• set_grants: Replace permanent grants. Replaces the permanent grants; time windows are untouched. Needs userId, grants. Asks for confirmation.
• set_time_window_grants: Give temporary access. Sets admin time windows: when, and at which doors or Access Scopes, a person can get in. mode replace (the default) swaps their admin time windows for these, [] clears them; mode add keeps the current ones and replaces any with the same windowId. Permanent grants and windows from an integration are untouched. Needs userId, timeWindowGrants. Asks for confirmation.
• decouple: Stop syncing a person. Freezes the row against integration and CCTV sync and clears its synced time windows, so admins control it by hand. Needs userId. Asks for confirmation.
• recouple: Resume syncing a person. Needs userId.
• logout: Sign a person out of the app. Ends every app session on their phone or email; returns how many were ended. Needs userId.
• resend_invite: Resend the app invitation. Emails one person the app invitation again; they need an email on file. Needs userId.
• send_invitation: Send app invitations. Emails the app invitation to up to 50 userIds, for example from door_access_users_read invitation_preview; send longer lists in batches. People who vanished, have no email or signed in since are skipped. Needs userIds. Asks for confirmation.