Read the scanner screen
Reader, zone, direction, NFC versus rotating QR, and what green and red actually tell you.
Owned by Door Staff · 11 steps · about 15 minutes
Why this exists
The scanner is designed so that the person holding the phone never has to make a judgement call. Every scan returns a colour and a reason, the screen is enormous and colour-coded so it reads at arm's length in the dark, and there is no 'override' button anywhere on it. If the screen is red, the answer is not to try again harder; it is to read the reason out loud.
Two credential formats arrive at that box and it matters that you can tell them apart. An NFC payload is a signed blob — a base64url JSON claim set with an HMAC after a dot. A rotating QR is the short string beginning CLB1: followed by the pass serial and an eight-digit code. The scanner sniffs the CLB1 prefix and labels the scan qr, otherwise nfc; you do not choose. The QR code exists because NFC readers have bad nights, and it rotates on a fifteen-second step with one step of tolerance either side. That is the whole anti-screenshot design: a code a guest forwarded to a friend earlier in the evening is dead within about forty-five seconds.
The other thing to internalise is that zones come from the pass row, never from the credential. The signing scheme is symmetric HMAC, so a payload's own zone claim is not a trust boundary — if a presented payload claims zones that differ from the stored ones, that is a re-signed credential and it scans red for wrong zone. Your reader's zone is compared against what the database says the pass opens, and nothing else.
Finally, the reader you pick is not cosmetic. It carries the zone, the direction (in or out), and the anti-passback window. A credential scans red for wrong zone when your reader's zone is not among the zones written on the pass, so standing at VIP Door B and scanning general-admission tickets produces a wall of wrong-zone reds that are entirely your own doing. It does not run the other way. A VIP tier's ticket carries the main door as well as the VIP room, and a member's card carries every zone their groups grant, so neither is refused at the main door.
Before you start
- An employee session — door staff, venue manager or admin.
- At least one issued pass to scan. The seed mints membership cards for member@club.test and vip@club.test.
- The four seeded demo readers: Main A (zone A, in), VIP B (zone B, in), Exit A (zone A, out) and the bar POS.
Practise with
| Persona | Password | Note | |
|---|---|---|---|
| door_staff | door@club.test | door123 | door shift account: scanner + guest list, nothing else |
| member | member@club.test | member123 | holds a seeded pass and membership card to practise scans against |
| venue_manager | manager@club.test | manager123 | shift lead: implies door_staff, plus intake, sales, guest list, marketing |
Steps 1 — Venue Manager
their manual →Chooses which readers exist for the night and reads the scan log afterwards.
-
1Before the shift, open the Access Console and check the readers your door will use are active and pointed at the right zones and directions.Expected result A Readers table with name, zone, direction, passback window, status, last seen and cache freshness.Watch out for A reader with status disabled will refuse every scan with reader_disabled, not with a normal red verdict. Fix it here before doors, not at the door.
Steps 2–8 — Door Staff
their manual →-
2Open the scanner and pick your reader from the dropdown. Check the two badges underneath it: they show the zone and the direction you are now scanning as.Expected result Badges reading something like zone A and in. The choice is remembered in the browser, so it survives a reload.Watch out for The remembered reader is the classic first mistake of a second shift. If you worked the VIP door last night and the main door tonight, the page will happily reload with VIP B still selected.
-
3Learn to recognise the two payload shapes. A long string with a dot near the end is an NFC payload. A short string starting CLB1: is a rotating QR. The box accepts either — paste it, or let the reader hardware type it, and press Enter.Expected result The scan fires on Enter or on the Scan button; the input clears itself immediately so the next guest can go.Watch out for The input clearing is intentional. If you need to know what you just scanned, read the Recent scans table below — do not try to scroll the input back.
-
4Scan a valid pass and read the green screen properly. It shows a tick and Welcome, then the holder name and their roles, the event, the tier and the zones the pass opens, the entry count, and the round-trip latency in milliseconds.Expected result A full-screen green panel and a new row at the top of Recent scans.Watch out for Green on a door reader means the whole gate chain passed: signature or TOTP, revocation blacklist, pass status, order paid, event window, zone, and anti-passback. It is not a partial verdict — there is nothing else for you to check. One green is narrower than that and it is not yours: a membership card presented at a BAR reader returns green as soon as the card authenticates (access/service.py:1403), deliberately skipping anti-passback and writing no check-in. It answers 'is this a member', not 'has this person come through a door', so a bar green never tells you anyone is inside the building.
-
5Now scan the same credential a second time on the same in reader. Watch it go red with Already Scanned.Expected result A red panel reading Already Scanned.Watch out for This is anti-passback, and it is the guard that matters most in practice. The seeded in readers use a window of zero, which means infinite — once a serial is checked in it cannot check in again until it checks OUT on an out reader. The second person holding that screenshot is exactly the problem this exists to catch.
-
6Switch to the Exit A reader (direction out) and scan the same pass to check the guest out. Then scan them back in on the in reader.Expected result Green on the way out, then green on the way back in with the entry count incremented.Watch out for Scanning a guest OUT who never came in is red with Not Checked In. That is not an accusation of anything — it usually means they entered on a different door before you started, or on a reader that was offline.
-
7Take a general-admission pass to the VIP B reader and scan it. Read the wrong-zone red.Expected result A red panel reading Wrong Zone.Watch out for Zone codes and role zones are written differently in the two halves of the system — the event side uses A, B, C and the role side uses zone_a, zone_b, zone_c — and the scanner normalises them before comparing, so A really does equal zone_a and a spelling mismatch is never the cause. What the red DOES tell you is narrower: your reader's zone is not among the zones that pass opens. Two things produce that and only one of them is the guest. Check your reader badges first — the wall of wrong-zone reds this manual warns about two steps up is the same verdict, caused by the reader you picked — and only then tell somebody they do not hold the zone. There is also a second, rarer zone red, Zone Closed For This Event: that one means the event dropped the zone after the pass was issued, and it is never the guest's doing.
-
8Understand the bar reader, because it behaves differently on purpose. Scanning a membership card on the bar POS reader authenticates the member and returns their prepaid balance and available tab — and deliberately does NOT check anybody in or consume an entry.Expected result Green with a credit line showing prepaid and tab amounts.Watch out for Do not use the bar reader on the door. It never records an entry, so a night scanned on the bar reader leaves you with no check-in count at all.
Steps 9–10 — Member
their manual →Presents the credential — and can show you what the rotating QR looks like from their side.
-
9From the guest's side: open your wallet and show the pass you are presenting.Expected result Your passes with status and the zones each one opens.
-
10Show the rotating QR fallback and watch the seconds-remaining counter tick down.Expected result A payload plus seconds_remaining and a fifteen-second period.Watch out for If your pass is suspended because you listed it for resale this returns a 409 rather than a code, and if it has been revoked it returns a 410. Neither is a network problem.
Steps 11 — Venue Manager
their manual →Chooses which readers exist for the night and reads the scan log afterwards.
-
11After the doors settle, pull the scan log filtered to your event to see the shape of the night: greens, reds by reason, and the latency percentiles.Expected result Log rows plus a stats block with count, green, red, p50, p95 and max milliseconds.Watch out for A cluster of reds all sharing one reason code is nearly always a configuration mistake — the wrong reader selected, or a reader pointed at the wrong zone — not a crowd of fraudsters.