Data and Security

Language: English | Deutsch

Data & Security

Data storage

All persistent data lives in /data/ inside the add-on container — mapped to HA persistent storage, survives updates and restarts.

File	Contents
/data/shots.json	Machine data for all synced shots
/data/annotations.json	Notes and ratings (separate file, sync-safe)
/data/coffee_library.json	Bean and grinder library
/data/trash.json	Trashed shots (auto-purged after 30 days)
/data/blocklist.json	Shot IDs that should never be re-synced

API endpoints (internal)

Endpoint	Method	Description
/shots.json	GET	All shots with annotations
/api/status	GET	Sync status, shot count, HA connection, GLP version
/api/sync	POST	Trigger manual sync (rate-limited: max once per 30 s)
/api/shots/:id/annotate	POST	Save annotation for a shot
/api/shots/:id/delete	POST	Move shot to trash
/api/live/data	GET	Latest live data (fetch-polling, 1-second interval)
/api/debug/machine	GET	Raw response from controller /api/system/status

Security

API token

Port 8099 is protected by an automatically generated API token:

• On first start the add-on generates a random 64-character token using crypto.randomBytes(32) (OS-level CSPRNG) and stores it in /data/api_token.txt.
• /api/status is the only public endpoint — it returns the token so clients can self-configure.
• All other /api/* and /shots.json requests must include the X-GLP-Token: <token> header.
• Requests via HA Ingress bypass the token check — they are already authenticated by HA.
• The browser UI and HA integration pick up the token automatically. No manual setup required.
• To rotate the token: delete /data/api_token.txt and restart the add-on.

Other

• HA API access is read-only via the Supervisor token (SUPERVISOR_TOKEN). The only write operation is toggling the configured switch_entity when using the smart plug feature.
• All user-supplied inputs (annotations, library entries) are validated server-side with field length limits.
• Shot IDs are validated as integers within the known range before any file operation.

Sync behavior

The sync is incremental and one-directional: the add-on tracks the highest local shot ID and only fetches shots with a higher ID from the machine. Shots deleted locally (and added to the blocklist) are never re-downloaded.