Administrator Guide

Complete reference for Hygate administrators.

Overview

Administrators have full system access. You can manage integrations, team members, doors, devices, locations, payments, reports, and security settings.

Dashboard

The Dashboard gives you a real-time overview of your entire workspace.

What You'll See

Active Sessions — Number of currently running device sessions, with a countdown for each
Recent Payments — Latest payment transactions with status, amount, and timestamp
Module Health — Connection status for TTLock, Shelly, and Stripe integrations
Revenue Overview — Total revenue for the current period
System Overview — Counts of locations, doors, and devices

Reading the Metrics

Metric	What It Means
Active Sessions	Devices currently in use. Each running session shows a countdown circle.
Revenue	Total payments received (succeeded only). Excludes failed and refunded.
Doors	Total doors synced from TTLock and added to Hygate.
Devices	Total Shelly devices synced and added.
Locations	Physical locations configured in your workspace.

Health Indicators

Green indicators mean the integration is connected and responding. Red indicates a problem — check your integration credentials in Settings.

Doors

Doors are smart locks synchronized from TTLock. Each door can be configured with its own price and duration.

Adding Doors

Navigate to Doors
Click Sync from TTLock
Wait for the lock list to load from TTLock
Select the checkboxes next to doors you want to add
Set the Location for each door
Optionally override the Name, Price, and Duration
Click Add Selected Doors

Already-added doors appear disabled in the sync list so you don't add duplicates.

Managing Doors

Once added, you can:

Edit details — Change name, description, price, duration, notes
Change status — Switch between Active, Passage Mode, and Maintenance Mode
Refresh sync — Manually refresh TTLock sync status
Generate QR Code — Create a branded PDF QR code for guests
Delete door — Remove the door from Hygate (does not delete from TTLock)

Door Status Modes

Status	Behavior	When to Use
Active	Normal operation. Guests can purchase access.	Default working state.
Passage Mode	Door stays unlocked. No payment required. Guests see free access message.	Open hours, shared areas, during events.
Maintenance Mode	Door unavailable. Payments blocked. Maintenance message shown.	Repairs, cleaning, temporary closure.

QR Code PDF Generator

The QR code PDF is a branded flyer guests can scan to pay for access.

Customization options:

Header text — Title shown at the top (e.g., "Front Door Access")
Subtitle — Secondary text line
Accent color — Theme color for the PDF (hex code)
Footer text — Fine print or instructions at the bottom

QR code placement tips:

Print at high resolution (minimum 300 DPI)
Laminate outdoor codes to protect from weather
Position at eye level, 120–150cm from the ground
Avoid placing on reflective or curved surfaces
Include your logo in the header for brand recognition

Passage Mode Deep Dive

Passage mode unlocks the door on a schedule. When activated:

The door unlocks automatically at the configured start time
The lock stays open during the passage window
No QR payment is required — the public page shows "Free Access" or "Open Access"
Guests scanning the QR code see a green "Open Access" indicator instead of a payment page

Common use cases:

Gym front desk during staffed hours
Hotel lobby during check-in hours
Office building during business hours
Event venues during peak times

Security note: Passage mode bypasses the payment flow. Only enable it during periods when physical security staff are present.

Maintenance Mode Deep Dive

Maintenance mode displays a branded unavailable page:

[Your Logo]
[Door Name]
Currently Closed for Maintenance

Please check back later or contact the front desk.

Payments are blocked immediately
Existing active sessions are not affected
The door lock itself is not changed — Hygate just stops accepting new payments
Operators can enable/disable maintenance mode

Door Synchronization

Hygate syncs with TTLock in two ways:

Background sync — Runs continuously to keep door status up to date
Manual refresh — Click Refresh on any door to pull the latest status from TTLock

Background sync detects:

Lock state changes (locked/unlocked)
Passage mode status
Battery levels (if reported by the lock)
Connectivity status

Devices

Devices are IoT relays synchronized from Shelly. Each device controls a physical appliance (washer, dryer, EV charger, etc.).

Adding Devices

Navigate to Devices
Click Sync from Shelly
Wait for the device list to load
Select the devices you want to add
Set the Location
Optionally override the Name and Description
Click Add Selected Devices

Usage Plans

Usage plans define what guests pay and how long they get.

Each plan has:

Field	Description
Program Name	Display name (e.g., "1-Hour Wash")
Description	Optional details shown to guests
Duration	Session length in minutes
Delayed Start	Grace period before timer begins (minutes)
Price	Amount in your configured currency
Sort Order	Display order on the payment page
Active	Whether guests can select this plan

Delayed start exists because:

Laundry guests need time to load clothes before the machine starts
EV charging guests need to connect the cable before power activates
Gym equipment needs a wipe-down and setup period

Example plan configuration:

Plan	Duration	Delay	Price
Quick Wash	30 min	5 min	€1.50
Standard Wash	60 min	5 min	€2.50
Extended Dry	45 min	2 min	€1.50
EV Fast Charge	120 min	10 min	€8.00

Managing Devices

From the Devices list, you can:

Edit details — Change name, description, location
Power ON / OFF — Manually toggle the relay
Maintenance mode — Block new purchases without affecting active sessions
Manage usage plans — Add, edit, reorder, or deactivate plans
Delete device — Remove from Hygate

Device Status

Status	Behavior	When to Use
Active	Normal operation. Payments accepted. Relay controllable.	Default state.
Maintenance Mode	New payments blocked. Existing sessions continue.	Repairs, inspections, cleaning.

Relay Control

Hygate sends real-time commands to Shelly devices:

Power ON — Activates the relay. Guest session timer starts.
Power OFF — Deactivates the relay. Session ends.
Auto-OFF — Sessions automatically end when time expires.

Relay commands are retried automatically. If a command fails, the system logs the error and retries on the next reconciliation cycle.

Locations

Locations group your doors and devices into physical spaces.

Creating Locations

Go to Locations
Click Add Location
Enter a Name (e.g., "Main Building", "Airport Locker Room A")
Enter an Address (optional, for reference)
Save

Managing Locations

Rename — Change the location name or address
View contents — See all doors and devices within a location
Delete — Remove the location (all associated doors and devices are unlinked)

Naming Conventions

Good location names:

Reference the physical space: "Downtown Lobby", "Beach Club Entrance"
Include floor or zone: "Floor 2 - Dryers", "Zone B Lockers"
Distinguish duplicates: "Airport T1 - Locker Bay 1", "Airport T2 - Locker Bay 1"

Operators can only rename locations, not create or delete them. This prevents accidental workspace disruption.

Payments

The Payments module shows every payment transaction.

Viewing Payments

Column	Description
Amount	Payment total in your currency
Status	PENDING, SUCCEEDED, FAILED, or REFUNDED
Module	Whether the payment was for a door or a device
Location	Where the payment originated
Guest Email	Email provided by guest (if any)
Date	When the payment was processed

Filtering

Filter payments by:

Date range — Custom period or preset (Today, This Week, This Month)
Module — Door or Device
Status — Any status combination
Location — Specific location

Payment Lifecycle

Guest initiates payment
        │
        ▼
  PENDING (Stripe Payment Intent created)
        │
        ▼
  Payment processed by Stripe
        │
   ┌────┴────┐
   │         │
SUCCEEDED  FAILED
   │         │
   ▼         ▼
Access granted  Error shown to guest
   │
   ▼
REFUNDED (if admin initiates refund)

Refunds

Refunds can be initiated from the Stripe Dashboard directly. Refunded payments appear with a REFUNDED status in Hygate.

Refunds must be processed through Stripe. Hygate does not currently support refund initiation from the admin panel.

Reports

Reports provide business intelligence from your payment data.

Revenue Reports

View	Description
Daily	Revenue broken down by day
Weekly	Revenue aggregated by week
Monthly	Revenue aggregated by month

Usage Analytics

Total sessions completed
Average session duration
Peak usage times
Revenue per device/door
Revenue per location

Exporting Data

Export reports as CSV for further analysis in spreadsheets or BI tools.

Key Performance Indicators

KPI	Formula	Why It Matters
Average Revenue Per Session	Total revenue ÷ Sessions	Indicates pricing optimization potential
Occupancy Rate	Active hours ÷ Available hours	Measures utilization of your assets
Revenue Per Location	Location revenue ÷ Sessions	Identifies top-performing locations
Cancellation Rate	Cancelled sessions ÷ Total sessions	Indicates technical issues or guest dissatisfaction

Sessions

Sessions track active and completed device access.

Session States

State	Description
ACTIVE	Session is running. Relay is ON. Countdown is active.
COMPLETED	Session ended normally. Timer expired.
CANCELLED	Session ended early. Relay was turned off before time expired.

Viewing Sessions

Filter by status (Active, Completed, Cancelled)
Filter by device or location
Search by guest token

Session Details

Each session shows:

Device name and location
Usage plan used
Duration (configured vs actual)
Started at / Ended at
Guest token
Failure reason (if cancelled)

Admin Recovery Actions

For ACTIVE sessions that need manual intervention:

Action	When to Use
Force End	Session is stuck. Guest has left but relay won't turn off.
Mark as Failed	Technical issue caused session failure. Logs the failure reason.

Session Lifecycle (Deep Dive)

Guest selects usage plan
        │
        ▼
  Payment initiated (Stripe)
        │
        ▼
  Payment confirmed (webhook)
        │
        ▼
  DeviceSession created (status: ACTIVE)
        │
        ▼
  Grace period begins (delayMinutes)
  ┌─────────────────────────────────┐
  │ Guest loads laundry / connects  │
  │ cable / prepares equipment      │
  └─────────────────────────────────┘
        │
        ▼
  Timer starts / Relay turns ON
        │
        ▼
  Countdown visible to guest
  (session countdown page, polling every 2s)
        │
        ▼
  Timer reaches 0
        │
        ▼
  Relay turns OFF (automatic)
  Session marked COMPLETED

Startup Recovery

When the server restarts, Hygate automatically checks for active sessions:

Expired sessions — Relay is turned off, marked as COMPLETED
Valid sessions — Relay state is verified and reconciled

This prevents orphaned active sessions after server downtime.

Audit Logs

Audit logs track every significant action taken in the system.

What's Logged

Category	Examples
User actions	Login, logout, password change, 2FA setup
Configuration changes	Stripe keys updated, TTLock credentials changed
Security changes	2FA policy changed, user deactivated
Operational events	Door status changed, device switched, session recovery

Viewing Logs

Each log entry shows:

Action — Human-readable description (e.g., "Updated TTLock credentials")
User — Who performed the action
Timestamp — When it occurred
Details — Expandable JSON with the full context

Filtering

Filter logs by:

Action type — Category of action
Date range — Time period

Compliance Benefits

Audit logs support:

Security auditing — Track who accessed what and when
Change history — Know exactly what changed and who made it
Incident investigation — Reconstruct events leading up to an issue
Compliance reporting — Provide evidence for regulatory requirements

Settings

The Settings module manages your workspace configuration.

General Settings

Setting	Description	Default
Company Name	Displayed on payment pages and emails	—
Payment Page Title	Shown in browser tabs and page headers	—
Default Access Price	Price for new doors (EUR)	€1.00
Default Access Duration	Duration for new doors (minutes)	60
Currency	Payment currency	EUR
Trust Period (Days)	Days a trusted device bypasses 2FA	30
TTLock Enabled	Enable TTLock module	true
Shelly Enabled	Enable Shelly module	true

Branding Settings

Customize the appearance of public payment pages:

Logo — Your company logo (URL)
Brand Color — Primary accent color (hex)
Header Text — Welcome message on payment pages
Footer Text — Fine print or contact info

Security Settings

Method	Description
Disabled	No two-factor authentication required
Email OTP	6-digit code sent to user's email on login
Authenticator App	TOTP code from an authenticator app
Either method	User chooses between email OTP and authenticator app

Team Management

Action	Description
Invite User	Send an invitation to a new team member
Change Role	Switch a user between Administrator and Operator
Deactivate	Disable a user's access without deleting them
Delete	Permanently remove a user from the workspace

Integration Configuration

Detailed guides for each integration:

Integrations

TTLock

Connect your TTLock smart locks to Hygate.

Step	Action
1	Create a TTLock developer account at ttlock.com
2	Create an application to get your Client ID and Client Secret
3	Enter credentials in Settings → TTLock
4	Click Test Connection
5	Save

What Hygate syncs:

Lock list (name, model, firmware version)
Lock state (locked/unlocked)
Passage mode settings
QR code access codes

What Hygate controls:

Lock/unlock commands
Passage mode enable/disable
QR code generation and refresh

Shelly

Connect your Shelly IoT relays.

Step	Action
1	Create a Shelly Cloud account at shelly.cloud
2	Generate an Auth Key from your Shelly Cloud settings
3	Enter the Auth Key in Settings → Shelly
4	Click Test Connection
5	Save

What Hygate syncs:

Device list (name, model, online status)
Relay state (on/off)
Channel configuration

What Hygate controls:

Relay ON/OFF commands
Device status (active/maintenance)

Stripe

Connect Stripe for payment processing.

Step	Action
1	Create a Stripe account at stripe.com
2	Get your API keys from Dashboard → Developers → API keys
3	Configure your webhook endpoint: `https://your-domain/api/stripe/webhook`
4	Subscribe to events: `checkout.session.completed`, `payment_intent.succeeded`, `charge.refunded`
5	Get your Webhook Signing Secret
6	Enter all three values in Settings → Stripe
7	Click Test Connection
8	Save

Webhook endpoint format: https://your-domain.com/api/stripe/webhook

Email (Resend)

Connect Resend for email OTP delivery.

Step	Action
1	Create a Resend account at resend.com
2	Create an API key from the Resend Dashboard
3	Verify your domain for sending
4	Enter the API key in Settings → Email
5	Set your From Email address
6	Click Test Connection to send a verification email
7	Save

Security Best Practices

Authentication

Enable 2FA for all administrator accounts
Use Authenticator App over Email OTP for better security
Use strong passwords — minimum 12 characters with mixed types
Enable trust period — Trusted devices remember 2FA for 30 days

Integration Security

Rotate API keys regularly — Rotate Stripe, TTLock, and Shelly keys every 90 days
Use environment variables — Never store credentials in plain text
Restrict Stripe webhooks — Limit to specific IP addresses if possible
Monitor audit logs — Review weekly for unusual activity

Access Control

Principle of least privilege — Assign Operator roles to team members who don't need admin access
Review team access quarterly — Remove inactive users
Separate environments — Use separate Hygate instances for production and testing

Data Protection

Encryption at rest — All integration credentials are encrypted in the database
Secure session management — JWT-based sessions with configurable expiration
Audit logging — All significant actions are tracked

For detailed security guidance, see Security Best Practices.