docs
/
AI skills

Access control for doors and cards

Physical access in Business Made › Access — a tree of zones, the access points (doors) in them, the input devices that read cards and the granting devices that open; who may pass as access groups and people allowed or denied, PIN policies, capacity, lockdown and evacuation; cards and fobs imported, issued, suspended, replaced and revoked; why a door said no, read from the access event log; and what reaches real hardware.

Access control decides on the server who may pass which door. It is the Access section of Business Made (/access). The API is appengine access-control/… (src/access-control/).

The pieces, all ordinary records:

RecordWhat it is
access_zoneA place, in one tree: site → building → floor → room… Its scopePath (e.g. /hq/floor-3) is computed from parent.
access_pointA door or entrance: a group of devices in one zone.
access_deviceAn input device: a card reader, keypad, QR scanner, terminal, plate camera, handheld. It calls the engine with what it read.
device_configA granting device: a lock, gate, barrier, turnstile or elevator on a Device Hub. The engine tells it to open.
access_groupPeople who go through doors together ("Night cleaners"). Not user groups, not roles.
access_policyPIN rules.
access_credentialA card, fob, QR, mobile, plate, fingerprint or face code, linked to one person.
access_eventOne line per read (granted, denied, alarm) and per credential change.

The same card signs staff in at the POS when it is held by their login (user). Access cards registered from Appmint Mobile (NFC access cards) and the cards issued in an onboarding journey (Onboard a new hire) are access_credential records too, and show here.

Event zones and ticket scanning are a different system: Event tickets and check-in. Readiness's access gate holds back platform roles and user groups, which doors don't read: see Training and readiness.

Ask first

  • The places: the sites, buildings, floors and rooms, as a tree. Which have a capacity?
  • The doors: each entrance, which zone it leads into, and what is fitted: a reader, a keypad, a lock on a hub.
  • Who goes where: teams (access groups) and one-off people, per zone. Anyone to keep out of a place the zone above lets them into?
  • PINs: where a PIN is needed with the card, and of whom (everyone, or some groups).
  • The cards: a box of numbered cards to load, or cards issued one by one. Who gets one, valid from and until when.
  • Visitors: guest badges, with name and who hosts them.

Steps

1. Access › Zones: the zone tree

repo_create with datatype access_zone, one per place, parents first:

{ "datatype": "access_zone", "isNew": true,
  "data": { "name": "hq", "title": "HQ", "kind": "site", "location": "<business location name>" } }
FieldValues
nameRequired, unique, letters, digits, - and _. Every other record points at zones by this name.
title, kindkind: global, country, state, site, building (default), floor, wing, room, cage, rack, parking, lane, perimeter.
parentThe parent zone's name. Empty is the top of the tree.
capacityMost people inside at once. Empty is no limit (see step 6).
location, timezone, addressThe Business Location it is, or a time zone and address when it isn't one.
allow, deny, policyWho may pass and the PIN policy (step 3).

The engine fills scopePath on save, for the zone and everything beneath (tested: a room under skilltest-access-site read /skilltest-access-site/skilltest-access-room).

Hands on: each zone's name. Check: /access/zones?zone=<name> shows the zone in the tree with its path.

2. Access › Zones: doors and devices

The door. repo_create datatype access_point, { name, title, zone: "<zone name>" }. It may carry its own allow, deny and policy.

The reader. repo_create datatype access_device:

FieldValues
name, titleRequired, unique.
kindRequired. card-reader, keypad, qr-scanner, fingerprint, plate-camera read cards, QR, fingerprints and plates. terminal, computer and handheld say per read.
accessPointThe door's name. Without one every read is denied no_policy.
hasKeypadPIN rules apply only at keypads, terminals and devices with this on.
triggersThe granting devices this reader opens (their device_config names). Empty: reads are decided and logged, nothing opens.
statusactive or disabled (refused with "Device is disabled", tested).

Then give it its key: call_appengine POST /access-control/devices/<name>/key. The key comes back once (acd_…) with "Save this key now — only its hash is stored. Mint again to replace it." On screen: saving Add input device makes the key and a connection string Server=…;OrgId=…;DeviceName=…;ApiKey=….

Minting again replaces the key. The reader at the door stops working until it is given the new one. Ask before re-keying a device in use.

The lock. A granting device is a hub endpoint: connect the hub and its relay first (Setting up a hub, Connecting devices). Then Add granting device on the zone: pick the hub, its endpoint, a kind (lock, gate, barrier, turnstile, elevator), the access point and the readers that trigger it. That gives the device_config the unlock capability, access.accessPoint, and adds its name to each reader's triggers.

Hands on: the access point and device names. Check: the zone's devices on /access/zones?zone=<name>&dt=input. A reader reads online once it has called in within a day (tested).

3. Access › Groups and Policies: who may pass

Access groups. repo_create datatype access_group, { name, title, employees: [<bm_employee sk>], users: [<user sk>] }. Employees go in employees, people with only a login in users. An employee and their linked login are one person at the door. On screen: /access/groups?group=_new.

Rules are allow and deny on a zone, an access point or an input device, each { groups: [<group name>], employees: [<sk>], users: [<sk>] }. A read is decided over one chain, nearest first: input device → access point → zone → each zone above (access-rules.ts 136–154):

What matchesResult
A deny anywhere on the chainDenied, denied_by_policy. A deny always wins.
Otherwise an allow anywhereGranted. An allow on a site lets its members into every room in it (tested). An allow on a door adds that door only.
NothingDenied, no_policy.
A rule that isn't an object of listsDenied, rule_error (tested with allow: ["x"]).

Customers match only by their own id in users. Guests never match: a guest credential identifies, it opens nothing.

To change a rule, send the whole object: repo_update merges patch one level deep, so { "allow": { "groups": [...] } } replaces every list in allow. On screen: Edit zone (/access/zones?edit=<name>), or a person's drawer in Credentials gives one zone by name.

PIN policy. repo_create datatype access_policy, { name, title, requirePin, pinGroups }, then set policy: "<name>" on a zone, access point or reader. requirePin: off, everyone, or groups (members of pinGroups). Zones below inherit it. Every policy on the chain applies and the strictest wins. A person who set a PIN on their card is always asked. A policy named but missing asks everyone (tested).

Check: what the door will decide, without a read:

  • GET /access-control/holders/<datatype>/<id>/zones lists every zone the person may enter, with the zone whose rule lets them in and how (group Night cleaners, by name). Tested: an allow on the site gave both the site and the room.
  • GET /access-control/views/zone/<name>: zone.effective lists every allow and deny in force and where each comes from, and the policy.

On screen: Who may enter on the zone.

4. Access › Credentials: cards to people

Load a box of cards (optional): POST /access-control/credentials/import:

{ "type": "card", "batch": "HID-2026-10", "range": { "from": 1, "to": 500, "prefix": "HQ", "pad": 4 } }

or "codes": ["04A1B2C3", …]. batch is required. At most 5,000 per import. Card and fob numbers are stored upper-case, so aa11bb22 and AA11BB22 are one card. Numbers already known are skipped and listed in skipped (all tested). They go in as available.

Issue one: POST /access-control/credentials:

{ "code": "HQ0001", "type": "card",
  "holder": { "datatype": "bm_employee", "id": "<sk>" },
  "validFrom": "…", "validUntil": "2026-12-31T23:59:00Z", "pin": "4321", "label": "Lanyard 3" }
holder.datatypeWho
userStaff with a login. Use this for staff who have one: POS card sign-in only accepts a card held by the user (users.service.ts 1762–1766). Studio's Issue does the same, picking the employee's linked login.
bm_employeeStaff with no login. Opens doors; doesn't sign in at the POS.
customerA storefront account.
guestA visitor: name (required), email, phone, company, host. Opens nothing.

A number in the pool (available or returned) is handed to them. An unknown number is created and issued. A number already active is refused: "That credential is active, not in the pool" (tested). pin is 4 to 8 digits. Each issue clears any PIN the card had unless you send one. Without a holder: "holder is required". A guest without a name: "A guest needs a name" (tested).

On screen: Issue (/access/credentials?new=issue), Import (?new=import), Pool (?new=pool), Look up (?new=lookup, or GET /access-control/credentials/lookup?code=).

Hands on: the credential's sk. Check: /access/credentials?openId=<sk> shows it Active with its holder and the zones they can enter.

5. Access › Credentials: change a card

All POST /access-control/credentials/<sk>/…, each writing a credential event:

CallBodyWhat it does (tested)
status{ status, note? }active, suspended, returned, expired, revoked, lost, available. Only active opens. available puts it back in the pool and clears the holder, PIN and dates. Others keep the holder.
bulk-status{ ids | batch | holder:{datatype,id}, status, note? }Every card in a list, a batch, or held by one person. Answers { changed }.
pin{ pin? }Sets or clears the PIN, and lifts a PIN lockout (back to active).
validity{ validFrom?, validUntil? }Sets both: one left out is cleared. Send both every time.
replace{ code, oldStatus?, note? }The new number goes to the same person with the same dates and PIN. The old one becomes lost (or revoked).
reassign{ holder, note? }Another person. The PIN is cleared.
assign{ holder, … }A pool card (available / returned) to a person, like issue.
historyGET, ?page=&pageSize=Every read and change on the card, newest first.

The Studio drawer's Reinstate is status active; Back to pool is available.

Stop before suspending, revoking or marking lost, singly or in bulk. The card stops working at every door and at POS sign-in at once. Say whose cards and how many, and wait for yes.

6. At the door: what it decides

A reader sends POST /access-control/read with headers orgid and x-device-key, body { device, code, pin?, method?, trigger? }. The AI can't send one: call_appengine sends no device key. Use step 3's checks. A person tries a real card, or Send a test read in the reader's drawer.

The checks, in order (access-control.service.ts 106–192). Each refusal is an ordinary answer { result: "denied", reason, zone, event }:

reasonOn screenWhen (all tested)
no_policyNot allowed in this zoneNo allow matches; the reader has no door or the door no zone; a guest card.
unknown_credentialUnknown cardThe number isn't known.
credential_inactiveCard not activeStatus isn't active, or validFrom is still ahead.
expiredCard expiredvalidUntil has passed.
lockdownPlace in lockdownThe zone or one above is locked down.
denied_by_policyBlocked by a deny ruleA deny matched.
rule_errorRule could not be checkedA rule is the wrong shape.
pin_requiredPIN neededAt a keypad, a PIN is asked and none was sent or the card has none.
pin_invalid, pin_lockedWrong PIN, Card lockedThe fifth wrong PIN in a row suspends the card.
capacity_fullPlace was fullThe zone has capacity people inside.

Errors instead of answers: a bad key is 401 "Unknown device or bad key". A reader with several triggers and no trigger gets 400 "This device opens several doors — say which one in trigger". A trigger not in its list gets 403 (tested).

A grant tells the granting device to unlock through its hub (unlocked: true when the hub answered). With no trigger, nothing opens and unlocked is false.

Who is inside is each person's latest granted read in the last 24 hours (GET /access-control/zones/<name>/occupancy). Nothing records leaving (see What it can't do yet).

7. Access › Overview: lockdown, remote unlock, alarms

CallWhat it does
POST /access-control/zones/<name>/lockdown { mode: "lock", reason }Every read in this zone and those beneath is denied lockdown. Each granting device there is sent lock.
…same with mode: "open"Evacuation: every active staff or customer card is granted, with no rule, PIN or capacity check (tested). Granting devices are sent hold-open.
DELETE /access-control/zones/<name>/lockdownRelease. Devices are sent release.
POST /access-control/devices/<device_config name>/unlock { note? }Opens one door now, logged as method remote.

Stop before every one of these. They send commands to real locks, gates and barriers on site, and a lockdown stops everyone in that part of the building. Say which zone or door, what will happen, and wait for yes. The answer lists each device and whether its hub took the command.

Hubs also report door alarms: door-forced, door-held-open, tamper and tailgate become events with result: "alarm".

8. Access › Events: why a door said no

ReadWhat it gives
GET /access-control/views/scope/<zone>/eventsEvents in a zone and everything inside, with counts by result and the top denial reasons. Filters: result, reason, type (access, credential), method, device, accessPoint, credential, holder=<datatype:id>, from, to, q, page, pageSize.
GET /access-control/views/eventsThe same for the whole business.
GET /access-control/views/person/<datatype>/<id>A person's cards, access groups, zones and recent events.
GET /access-control/views/exceptionsLockdowns, alarms in 24 hours, offline readers, full zones, denial spikes, totals.
GET /access-control/views/trends?period=today|7d|30d&zone=Granted and denied over time, denials by reason, busiest zones, top devices.
GET /access-control/views/search?q=Zones, doors, devices, credentials and people.

Each denial's event holds decidedBy: the rule, PIN check, capacity or lockdown that decided it, in words. Tested: "allow · group Skilltest Team · on zone Skilltest Site", "1 inside, capacity 1".

Check: /access/events?result=denied, /access.

What the holder can do

Signed-in staff and customers use client/access-control/…, the staff portal's My access (/staff-portal/access). All tested as a staff user:

CallWhat it does
GET …/credentials, GET …/zones, GET …/eventsTheir cards (without PIN), the zones they may enter, their events.
POST …/credentials/<sk>/pin { currentPin?, pin? }Set or change their PIN. Once one is set, currentPin is needed ("Current PIN is wrong"). Empty pin turns it off.
POST …/credentials/<sk>/lost { note? }Marks it lost; it stops at once. Someone else's card: "Credential not found".

Emails and notices

None. No step on this page sends an email, text or in-app notice: not issuing, suspending, a lockdown, a denial or an alarm. Tell people yourself.

When it's done

Tell the person:

  • the zone tree, each door and what is fitted, and which readers open which locks;
  • who may enter each zone (groups and people, and any deny), and where a PIN is asked;
  • the cards issued: whose, the number, the dates, PIN set or not;
  • anything sent to hardware (lockdown, unlock) and each device's answer.

Open /access/zones?zone=<name> and /access/credentials.

What it can't do yet

  • Nobody is ever recorded leaving. Reads carry no direction, so a person counts as inside a zone until they badge into another zone or 24 hours pass (access-control.service.ts 482–506). A zone with a capacity fills and stays full. Tested: with capacity 1, the second person was refused until the first badged elsewhere.
  • No time-of-day or day-of-week rules. A rule has no hours. Only a credential's validFrom / validUntil limits when.
  • QR and mobile codes are fixed. Nothing generates or rotates them. Each is a code you issue, like a card number.
  • Deleted access records skip Trash. Tested: zones, devices, credentials and events deleted left nothing in Trash. See Bring back deleted records.
  • Turning off one's own PIN is refused while any PIN policy for everyone exists in the business, even one set on no zone (access-credential.service.ts 310–317, tested: "Your business requires a PIN on your card").
  • validity clears the date you leave out (access-credential.service.ts 187).
  • Fields kept but not used: device_config.access.directions, failMode, heldOpenSeconds and pricing, and offline and charge on events. Held-open alarms come only from the hub.
  • A clock punch keeps the card number (cardUid) but doesn't check the credential (clock-event.service.ts 96).

Don'ts

  • Don't lock down, evacuate, release or unlock remotely without a yes. Each one moves real locks.
  • Don't re-key a reader that is in use without saying it will stop.
  • Don't send a partial allow or deny. It replaces the lists you left out.
  • Don't suspend, revoke or bulk-change cards without saying whose and how many.
  • Don't send validity with one date unless you mean to clear the other.
  • Don't give a guest card to someone who needs to open doors. Guests identify only.
  • Don't count on occupancy for safety. Nobody is recorded leaving.