API Overview

Technical reference for Hygate's API endpoints.

Note: This API reference is for developers integrating with Hygate. The public-facing APIs are documented below. All admin APIs require authentication via JWT.

---

Authentication

Admin endpoints require a valid JWT in the Authorization header:

Authorization: Bearer <jwt_token>

JWTs are obtained by logging in via /api/auth/login.

---

Public APIs

Public endpoints do not require authentication. These serve the guest-facing payment and session pages.

Door Payment

Create Door Payment Intent

POST /api/public/door/[uid]/intent

Creates a Stripe Checkout Session for door access.

Request:

{
  "email": "guest@example.com",
  "successUrl": "https://...",
  "cancelUrl": "https://..."
}

Response:

{
  "url": "https://checkout.stripe.com/..."
}

---

Get Door Info

GET /api/public/door/[uid]/info

Returns door configuration for the public payment page.

Response:

{
  "name": "Main Entrance",
  "price": 250,
  "currency": "eur",
  "duration": 60,
  "location": "Downtown Property",
  "branding": {
    "logo": "https://...",
    "color": "#0A84FF",
    "headerText": "Access Door",
    "footerText": "Contact: info@company.com"
  }
}

---

Device Payment

Create Device Payment Intent

POST /api/public/device/[uid]/intent

Creates a Stripe Checkout Session for device usage.

Request:

{
  "email": "guest@example.com",
  "planId": "plan_abc123",
  "successUrl": "https://...",
  "cancelUrl": "https://..."
}

Response:

{
  "url": "https://checkout.stripe.com/..."
}

---

Get Device Info

GET /api/public/device/[uid]/info

Returns device configuration and available usage plans.

Response:

{
  "name": "Washer 1",
  "description": "Standard front-loader",
  "location": "Floor 2 - Laundry",
  "usagePlans": [
    {
      "id": "plan_abc123",
      "name": "Standard Wash",
      "duration": 60,
      "delayMinutes": 5,
      "price": 250
    }
  ],
  "branding": { ... }
}

---

Activate Device Session

POST /api/public/device/[uid]/activate

Activates a device session after payment confirmation. Called by the webhook handler.

---

Branding

Get Public Settings

GET /api/public/settings

Returns branding settings for public payment pages.

---

Session

Get Session Status

GET /api/public/sessions/[token]

Returns the current status of a device session. Used by the guest session page for polling.

Response:

{
  "status": "ACTIVE",
  "startedAt": "2026-05-07T14:00:00Z",
  "endsAt": "2026-05-07T15:00:00Z",
  "remainingSeconds": 1800,
  "deviceName": "Washer 1",
  "planName": "Standard Wash"
}

---

Admin APIs

Locations

Method	Endpoint	Description
GET	/api/locations	List all locations
POST	/api/locations	Create a location
GET	/api/locations/[id]	Get location details
PATCH	/api/locations/[id]	Update a location
DELETE	/api/locations/[id]	Delete a location

Doors

Method	Endpoint	Description
GET	/api/doors	List all doors
POST	/api/doors	Create a door
GET	/api/doors/[id]	Get door details
PATCH	/api/doors/[id]	Update a door
DELETE	/api/doors/[id]	Delete a door
POST	/api/doors/[id]/status	Change door status

Devices

Method	Endpoint	Description
GET	/api/devices	List all devices
POST	/api/devices	Create a device
GET	/api/devices/[id]	Get device details
PATCH	/api/devices/[id]	Update a device
DELETE	/api/devices/[id]	Delete a device
POST	/api/devices/[id]/switch	Toggle relay ON/OFF
POST	/api/devices/[id]/force-off	Force relay OFF (admin)
GET	/api/devices/[id]/periods	List usage plans
POST	/api/devices/[id]/periods	Create a usage plan
DELETE	/api/devices/[id]/periods/[periodId]	Delete a usage plan

Sessions (Admin)

Method	Endpoint	Description
GET	/api/sessions	List sessions (filterable)
GET	/api/sessions/[token]	Get session details
PATCH	/api/sessions/[token]/end	Force end session
PATCH	/api/sessions/[token]/fail	Mark session as failed

Payments

Method	Endpoint	Description
GET	/api/payments	List payments (filterable)

Reports

Method	Endpoint	Description
GET	/api/reports	Revenue and usage reports

Settings

Method	Endpoint	Description
GET	/api/settings	Get all settings
PATCH	/api/settings	Update settings
GET/PATCH	/api/configs/stripe	Stripe configuration
GET/PATCH	/api/configs/shelly	Shelly configuration
GET/PATCH	/api/configs/ttlock	TTLock configuration
GET/PATCH	/api/configs/email	Email configuration

Team

Method	Endpoint	Description
GET	/api/team	List team members
POST	/api/team	Invite a new user
PATCH	/api/team/[id]	Update user role/status
DELETE	/api/team/[id]	Remove a user

Audit Logs

Method	Endpoint	Description
GET	/api/audit-logs	List audit logs (filterable)

Integrations

Method	Endpoint	Description
POST	/api/integrations/ttlock/test	Test TTLock connection
POST	/api/integrations/shelly/test	Test Shelly connection
POST	/api/integrations/stripe/test	Test Stripe connection

---

Webhook

Stripe Webhook

POST /api/stripe/webhook

Receives payment events from Stripe.

Required events:

• checkout.session.completed
• payment_intent.succeeded
• charge.refunded

Security: All requests are verified using Stripe's signature header (stripe-signature).

---

Cron Endpoints

These endpoints are called by external cron services or schedulers.

Endpoint	Schedule	Description
/api/cron/session-cleanup	Every 5 minutes	Expires sessions past their end time
/api/cron/session-reconcile	Every 2 minutes	Verifies relay state matches session state

Note: These endpoints should be protected from public access. Configure your cron service to call them internally or via a secret token.

---

Error Responses

All API endpoints return consistent error responses:

{
  "error": "Error message here",
  "code": "ERROR_CODE"
}

Common error codes:

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid JWT
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request data
INTERNAL_ERROR	500	Server error