Authentication
Send a bearer token in the Authorization header of each call:
Authorization: Bearer <token>
Give each system only the access that it needs. Give a control token only to a system that must control equipment.
| Web app token | Edge Server token | Edge Server control token | |
|---|---|---|---|
| Read API: sensors, thresholds | Yes | Yes | Yes |
| Read API: account (balance) | Yes | No (401) | No (401) |
| Read API: outlets, Controllers, Modbus points | No (401) | Yes | Yes |
| Write API | No (401) | No (403) | Yes |
| Where to make it | The Growbud web app | The Edge Server | The Edge Server |
Web app tokens
- Make an account in the Growbud mobile app.
- Sign in at growbud.app.
- Turn on API access in your profile settings. If API access is off, each call gets 403.
- Make a token. Set it to expire after 1 to 365 days (the default is 30), or never.
You can have 10 active tokens. You can revoke a token at any time. A web app token reads all the sensors on your account. It cannot change anything.
Edge Server tokens
Make these tokens on the Edge Server. An administrator runs these commands on the Edge Server computer, in the install folder (/opt/growbud-edge on Linux and macOS). On Linux, put sudo in front of each command. The user must be a user of that Edge Server: the administrator admin@growbud.local, or a member that an administrator added.
docker compose exec outlets node /app/edge-outlets.mjs token create \
--email admin@growbud.local --name "BMS" --days 365 --scope control
docker compose exec outlets node /app/edge-outlets.mjs token list
docker compose exec outlets node /app/edge-outlets.mjs token revoke <id>
The command shows the token one time only. Copy it immediately. --days is 1 to 3650 (the default is 365). Without --scope control, the token can only read sensors, outlets, Controllers and Modbus points.
- An Edge Server token works only on the Edge Server that made it.
- The token acts as its user. It gets the sensors, outlets and Controllers of the user's organization, and the sensors and outlets that the user owns. Other devices give 404.
- All members can switch outlets and Controller outputs, and write Modbus points.
- A revoked or expired token gets 401. The Edge Server records each Write API call with its token.
The Edge Server is on port 8443 on your network, for example https://192.0.2.10:8443. On the Edge Server computer itself, use https://localhost:8443. If your client does not trust its certificate, use curl with -k. On a Linux Edge Server computer with the desktop app, the installer puts the certificate in the system trust store.