How Access Decisions Work

This page explains the model behind every unlock: who is allowed through a door, in what order the checks run, and how Access Policies, grants, and safety checks interact. Read this first — every other page builds on these concepts.

The additive allow paths

A user can be allowed through a door by any policy or grant path. Passing one path is enough; one path never subtracts access supplied by another.

A policy matches only when Who AND Where AND When match. Policies are ORed together. Within Who, person-type/status conditions and tags are alternatives; within When, Weekly and One-time windows are alternatives. Where can include all facility doors, Access Scopes, individual doors, and exclusions.

Example: an "Active members" policy can cover the Front entrances scope Anytime, while a separate "Staff" policy covers all facility doors except the Plant room. A cleaner who matches neither can still receive a permanent grant to the Service entries scope.

Permanent grants and administrator/integration windows stay separate and additive. Policy edits and automatic import do not absorb or remove them.

Performance Hub staff synced into Users get door access through the editable Performance Hub staff policy, like any other policy. See Sync & Integrations.

The full decision sequence

When a user taps Unlock in the mobile app, the server checks the following, in order. The first failed check denies the unlock and records the reason in the Access Logs.

1. Is the user's access enabled? The Access enabled switch on the user's row in Users is an admin kill switch. Deleted, disabled, or sync-blocked users cannot unlock regardless of policy or grant. (For example: access_disabled.)
2. Is the door blocked or in maintenance? Explicit blockAllAccess denies every member path. Maintenance Force closed keeps the door locked and out of service for members; Force open keeps the door unlocked. Admins can unlock a door remotely; every admin unlock is recorded in Access Logs.
3. Does any additive allow path pass?
   • Policy path: any enabled named policy whose Who, Where, and When all match allows access.
   • Permanent-grant path: a facility, door, or containing Access Scope grant allows access when its optional hours match.
   • User window path: an administrator-owned Access Time Window is active and targets this door, facility, or a containing Access Scope.
   • Integration window path: a fresh source window is active and its configured scope_key mapping targets this door. Stale or unmapped source windows fail closed.
   • If none passes → denied (no_matching_policy_or_grant)
4. Geofence check (if enabled). Using the location the phone reports:
   • If the phone could not provide a location → denied (location_unavailable)
   • If the GPS reading is less accurate than the Require GPS accuracy better than setting → denied (gps_too_imprecise)
   • If the user's distance from the geofence centre exceeds radius + GPS accuracy + accuracy buffer → denied (outside_geofence)
   • The server is authoritative — a spoofed location on the phone is still rejected server-side.
5. Is the door controller online? If the controller hasn't reported in (heartbeat within the last 5 minutes), the unlock cannot be delivered (device_offline). If the command is sent but the controller doesn't confirm, the event is recorded as Timed out.
6. Unlock. The relay releases for the door's Hold time (1–30 seconds, default 10), then automatically re-locks. The event is recorded as Confirmed unlocked once the controller confirms.

One-time and bounded Weekly windows use integer Unix-second bounds and half-open boundaries [from, to): the start qualifies and the end does not. Weekly blocks use their declared IANA timezone and local wall-clock/DST rules. See Access Policy Schedules.

New clients receive outside_access_time_window detail plus structured next availability for a future-window-only door. During compatibility rollout, older clients continue receiving outside_access_hours as the primary reason so the door remains safely disabled and visible.

Existing configuration

Existing access configuration is imported into Access Policies automatically. The import preserves who had access, the doors or Access Scopes they could use, and the applicable hours as policy Who, Where, and When values. Administrators manage the resulting policies directly; there is no rollout mode or manual conversion workflow.

Geofence inheritance remains independent of Access Policies. Policy matches still pass through the effective geofence and all other safety/device checks.

What OTP sign-in does and doesn't do

Signing in to the mobile app (one-time code via SMS or email) is authentication only — it proves who the user is. It does not grant door access by itself. Every unlock is authorised individually using the decision sequence above. A user can be signed in to the app and still see "You don't have access to this door."

Glossary

Related pages

• Access Policies — Who, Where, When, and automatic import
• Access Policy Schedules — Anytime, Weekly, and One-time
• Access Scopes — reusable door bundles
• Geofencing — location checks
• Users — per-user grants and the kill switch
• Reference — every denial reason and default in one table
• Doors can also be included in Duress responses. See Response actions in Duress.