Skip to main content

Visitors

The Visitors page issues short-lived guest credentials — a one-shot way to give a contractor, delivery, or guest a 4-hour PIN without having to remember to disable them later.

A visitor is an auth_user with three things going for it:

  • is_visitor=true (so they don't clutter the regular Users page)
  • A unique 6-digit PIN auto-generated by the server
  • valid_from / valid_until populated, so the credential lifecycle the rest of GEM already enforces does the cleanup automatically

Issuing a Visitor PIN​

  1. Open Security → Visitors
  2. Click Issue Visitor PIN
  3. Fill in the form:
    • First Name — required. Used as the visitor's display label and for the access log.
    • Last Name — optional. Combined with First Name on the badge and in the visitor list.
    • Email / Phone — optional. Email is used to deliver the code if you check "Email the PIN" below.
    • Host — optional. The permanent user sponsoring this visitor. Surfaces in access logs and on the printed badge.
    • Photo — optional. Upload an image file (max 1 MB) or click Take Photo to capture from the device webcam. Appears on the printed badge.
    • Expires — pick a preset (1 hour / 4 hours / 1 day / 1 week) or Custom for a specific datetime.
    • Access Groups — select one or more Access Groups the visitor should belong to. The visitor inherits access from any rule those groups are referenced by.
    • Notify — check Email the PIN to the visitor on issue to send the code via email at issue time.
  4. Click Issue PIN

The next screen shows the PIN once, in plaintext, in green. This is the only time you can see it after the call returns — copy it, share it, send it. After that, it's only stored encrypted. From the same screen you can click Print Badge to print a 3.5" × 2.25" visitor badge with photo, host, and expiry.

How a visitor's PIN actually works​

Behind the scenes:

  1. The server generates a 6-digit PIN that doesn't collide with any existing PIN, RFID, or duress PIN in the system (retries up to 50 times across the 1M-value space).
  2. A new auth_user is created with is_visitor=true, enabled=true, and the requested valid_from / valid_until window.
  3. The PIN is encrypted via the same setCredential path used for permanent users — uniqueness checks run, and a credential_updated event fires so the central engine syncs the credential to every linked access device the visitor will reach (via the access groups they were added to).
  4. The visitor is appended to the selected access groups' user_ids.
  5. If "Email the PIN" was checked, an email is dispatched via the Mail service. The PIN body is plaintext — make sure your email channel is appropriate for the audience.

Lifecycle​

The visitor's lifecycle is enforced by the same machinery the rest of GEM uses:

  • Before valid_from — credentialActive() returns false; PIN entry at the keypad is rejected with unknown_credential.
  • During the window — normal access via the rules referenced by the visitor's groups.
  • After valid_until — same as before-valid_from, plus the periodic expiry sweep (every 15 min) calls propagateUserDisabled to suspend the user on linked access devices (so cached PINs on devices like 2N intercoms get cleared).
  • Revoke — click the trash icon in the visitor list (or toggle Revoked in the Manage modal) to set revoked_at = now. Same propagation as expiry; access stops immediately. Unchecking Revoked in the Manage modal clears the timestamp and re-syncs credentials to access devices.

Visitor list​

The grid shows every visitor account on the system, ordered by expiry (most-recent-first). Columns include Starts and Expires alongside the status chip:

StatusColorMeaning
ActivegreenWithin the valid window, not revoked
Pendingbluevalid_from is in the future
Expiredambervalid_until has passed
RevokedredAn admin revoked the visitor
Disabledgrayenabled = false (rare for visitors)

Per-row actions:

  • Print Badge (printer icon) — re-print the badge for any visitor at any time.
  • Revoke (trash icon) — only shown for active visitors; sets revoked_at = now immediately.
  • Manage (settings icon) — opens an edit modal (see below). Available for all visitors, including expired/revoked.

Past visitors stay in the list as audit history.

Managing an existing visitor​

Click the settings icon on any row to open the Manage Visitor modal. The header shows a live status pill that updates as you edit fields. You can change:

  • First Name / Last Name
  • Email / Phone
  • Host
  • Photo — upload, capture from webcam, or remove
  • Valid From / Valid Until — datetime pickers, with +1h / +4h / +1d / +1w quick-extend buttons that bump Valid Until from its current value (or now, if it's already past)
  • Revoked — checkbox; checking it sets revoked_at (preserving the original timestamp if already revoked), unchecking clears it

Clicking Save Changes runs the standard credential-sync path, so re-enabling a revoked visitor re-pushes their PIN to every linked access device automatically.

Tips​

  • For recurring visitor types (e.g. cleaners, dog walkers), pre-create a dedicated Access Group like cleaning_crew referenced by your rules. Selecting it here scopes the visitor to exactly the doors they need.
  • If you want a "permanent" guest account, use the regular Users page instead — visitors are designed to expire by default.
  • The 6-digit length is deliberate: 1M-value space avoids collisions, easier to read aloud / email than RFID, and quick enough to enter at a keypad.
  • The plaintext PIN is shown exactly once. There's no "show me the PIN again" — you'd revoke and reissue if it gets lost.
  • The badge prints from a hidden iframe via window.print() — works in any browser that supports printing, including "Save as PDF" flows. Page size is 3.5" × 2.25", which matches common badge stock and most label printers.