Glossary

Definitions of key terms and concepts in Hygate.

A

Access Code

A unique QR code generated by TTLock that unlocks a smart lock. Access codes are created after a guest successfully pays for door access and are single-use per session.

Access Token

An OAuth2 token used by Hygate to authenticate with the TTLock API. Hygate manages access token refresh automatically.

Active Mode

The default operational status of a door or device. In Active mode, doors accept payments and devices allow sessions. See also Maintenance Mode and Passage Mode.

Admin

Short for Administrator. See Administrator.

Administrator

A user role with full system access. Administrators can configure integrations, manage team members, access audit logs, and control all doors, devices, and locations. See also Operator.

Audit Log

A chronological record of significant system events — user actions, configuration changes, security events, and operational events. Only administrators can view audit logs.

Authenticator App

A mobile app (Google Authenticator, Authy, 1Password, etc.) that generates time-based one-time passwords (TOTP) for two-factor authentication. The recommended 2FA method in Hygate.

B

Backup Codes

One-time use codes generated when setting up two-factor authentication. They allow access to your account if you lose your authenticator app. Store them securely in a password manager.

Branding Settings

Configuration options in Hygate that control the appearance of public payment pages: logo, accent color, header text, and footer text.

C

Checkout Session

A Stripe concept. Hygate creates a Checkout Session when a guest initiates payment, redirecting them to Stripe's hosted payment page.

Countdown Circle

The visual timer shown on the guest's session page (/session/[token]). It displays time remaining in the current session and transitions through multiple states (running, finishing, complete, etc.).

Cron Job

An automated background task that runs on a schedule. Hygate has cron jobs for session cleanup (every 5 minutes) and session reconciliation (every 2 minutes).

D

Delayed Start

The grace period between when a guest completes payment and when the session timer begins. Used for loading time (laundry, EV charging, gym equipment). Configured in usage plans.

Device

A Shelly IoT relay registered in Hygate. Devices control appliances (washers, dryers, EV chargers) and offer time-based access plans. See also Door.

Device Session

A record tracking an active or completed device access session. Includes the guest token, payment reference, start time, end time, and status (ACTIVE, COMPLETED, CANCELLED).

Door

A TTLock smart lock registered in Hygate. Doors offer QR-code-based access with configurable pricing and duration. See also Device.

Dashboard

The main overview page in Hygate. Shows active sessions, recent payments, module health, revenue overview, and system statistics.

E

Email OTP

A 6-digit one-time password sent to the user's email address. Used as a two-factor authentication method when Email OTP is enabled.

Encryption Key

A secret key used to encrypt integration credentials stored in the Hygate database. Configured via the ENCRYPTION_KEY environment variable.

ENCRYPTION_KEY

An environment variable containing the 32-byte key used for AES-256 encryption of sensitive data at rest.

F

Force End

An admin action that immediately terminates an active device session. Sends a relay OFF command to Shelly and marks the session as COMPLETED.

G

Grace Period

See Delayed Start.

H

Health Indicator

A status badge on the Dashboard showing whether each integration (TTLock, Shelly, Stripe) is connected and responding. Green means healthy; red means there's a problem.

I

Idempotency

A property that ensures the same operation produces the same result, even when executed multiple times. Hygate uses idempotency keys to prevent duplicate charges from repeated webhook deliveries.

Invitation

An email sent to a new team member inviting them to join the Hygate workspace. The invitation contains a link to set their password.

J

JWT

JSON Web Token. The session mechanism used by Hygate. After login, Hygate issues a signed JWT that authenticates subsequent requests.

L

Location

A physical space that groups doors and devices. A location represents a building, floor, room, or zone. Locations are the top-level organizational unit in Hygate.

M

Maintenance Mode

An operational status for doors and devices where new payments are blocked. Existing active sessions continue unaffected. Used for repairs, cleaning, and temporary closures.

Module

A functional area in Hygate. The nine modules are: Dashboard, Doors, Devices, Locations, Payments, Reports, Sessions, Audit Logs, and Settings.

O

OAuth2

The authentication protocol used by Hygate to connect to TTLock. Hygate exchanges credentials for an access token and handles token refresh automatically.

Operator

A user role with limited access. Operators can manage doors, devices, locations (rename only), payments, reports, and sessions, but cannot configure integrations, manage team members, or view audit logs. See also Administrator.

OTP

One-Time Password. A 6-digit code used for two-factor authentication. Hygate supports Email OTP and Authenticator App (TOTP) codes.

P

Passage Mode

An operational status for doors where the lock stays unlocked on a schedule and no payment is required. Guests scanning the QR code see "Free Access" instead of a payment form. Configured in TTLock.

Payment Intent

A Stripe concept. Hygate creates a Payment Intent when a guest initiates payment, which Stripe uses to process the charge.

Payment Page

The public web page where guests enter payment details. For doors: /pay/[uid]. For devices: /use/[uid]. Customizable with branding settings.

Payment Session

See Device Session.

Prisma

The database ORM (Object-Relational Mapper) used by Hygate. Prisma maps database tables to TypeScript objects and manages database migrations.

Public Routes

URL paths that don't require authentication. In Hygate, public routes include payment pages, session countdown pages, access code display pages, and webhook endpoints.

Q

QR Code

A scannable two-dimensional barcode. Hygate generates QR codes for doors using TTLock's API. Guests scan QR codes to access the payment page.

QR Code PDF

A printable PDF generated by Hygate containing a branded QR code. Includes customizable header, subtitle, accent color, and footer text.

R

Reconciliation

A background process that runs every 2 minutes to verify that active sessions match their actual relay state. Catches sessions where the relay went off unexpectedly.

Refresh Token

An OAuth2 token used to obtain a new access token when the current one expires. Hygate stores and manages refresh tokens for TTLock automatically.

Relay

The switch inside a Shelly device that controls power to an appliance. Hygate sends ON and OFF commands to the relay to start and end device sessions.

Role

A user permission level. Hygate has two roles: Administrator (full access) and Operator (limited access).

S

Secret Key

A credential used to authenticate API requests. Hygate uses secret keys for Stripe, TTLock, Shelly, and Resend. All secret keys are encrypted at rest.

Session

In Hygate, "session" can mean:

A user's login session (managed with JWT)
A device session (active device access with countdown timer)

Session Cleanup

A cron job that runs every 5 minutes to expire stale sessions. Finds sessions past their end time, turns off the relay, and marks them as COMPLETED.

Session Countdown

The visual countdown circle shown to guests during an active device session. Polls the server every 2 seconds for updates.

Shelly

A brand of WiFi-connected IoT relays. Hygate integrates with Shelly Cloud to sync devices, control relays, and manage timed sessions.

Stripe

The payment processing platform used by Hygate. Handles card charges, webhooks, and payment confirmations.

Sync

The action of retrieving data from an external service (TTLock or Shelly) into Hygate. Keeps Hygate's door and device records up to date with the external service.

T

TOTP

Time-based One-Time Password. The algorithm used by authenticator apps (Google Authenticator, Authy, etc.) to generate one-time codes. Supported as a 2FA method in Hygate.

Trust Period

The number of days a verified device can skip two-factor authentication. Configured in Security settings (default: 30 days).

TTLock

A smart lock platform supporting Bluetooth, WiFi gateway, and keypad locks. Hygate integrates with TTLock to sync locks, generate QR access codes, and track lock status.

TTLOCK API

The REST API provided by TTLock for lock management, QR code generation, and lock control. Hygate communicates with TTLock via this API.

U

Usage Plan

A configurable pricing and time structure for device access. Each plan specifies a name, duration (minutes), grace period delay (minutes), price, and sort order. Multiple plans can be offered per device.

User Role

See Role.

V

Valid Session

An active device session where the relay is confirmed to be ON and the countdown timer is running. Reconciliation checks verify valid sessions against actual relay state.

W

Webhook

An HTTP callback from Stripe notifying Hygate of a payment event. Hygate receives webhooks at /api/stripe/webhook and uses them to confirm payments and create sessions.

Webhook Secret

A secret string used to verify that incoming webhooks are genuinely from Stripe. Configured in both Hygate and Stripe Dashboard.

Webhook Signature

An HMAC-SHA256 signature included in Stripe webhook requests. Hygate verifies this signature before processing any webhook to prevent spoofed requests.

Y

Y Combinator (Startup)

Not related to Hygate. Occasionally confused with "Y" in YAML files or configuration.