Skip to main content

Authentication

This section explains how authentication and authorization work in Homsai Backend v2: JWT tokens, permission model, and common security conventions for the APIs.

Overview​

This section explains how authentication and authorization work in Homsai Backend v2: JWT tokens, permission model, and common security conventions for the APIs.

JWT Authentication​

Token types​

The authentication flow uses two types of tokens:

  • accessToken
    • Short‑lived.
    • Sent with each protected API call in the Authorization header.
  • refreshToken
    • Longer‑lived.
    • Used to obtain a new access token without repeating the login with credentials.

Both tokens are issued by the POST /auth/login endpoint.

Login flow​

  1. The client sends a POST /auth/login request with user credentials in the JSON body.
  2. The backend validates the credentials and returns an accessToken and a refreshToken.
  3. The client stores these tokens securely and uses the accessToken in subsequent calls.

Example header for any protected request:

Authorization: Bearer <accessToken>

When the accessToken expires, the client can call GET /auth/token with the refreshToken (according to the documented scheme) to receive a new access token.

Authorization model​

Permissions​

Each functional area is protected by specific permissions. Typical examples:

  • Plants

    • PLANTS READ
    • PLANTS CREATE
    • PLANTS UPDATE
    • PLANTS DELETE

  • Devices

    • DEVICES READ
    • DEVICES CREATE
    • DEVICES UPDATE
    • DEVICES DELETE

  • Sensors

    • SENSORS READ
    • SENSORS CREATE
    • SENSORS UPDATE
    • SENSORS DELETE

  • Types & Signatures

    • SENSOR_TYPES READ/CREATE/UPDATE/DELETE
    • DEVICE_TYPES READ/CREATE/UPDATE/DELETE
    • LOAD_SIGNATURES READ/CREATE/UPDATE/DELETE

  • Energy & Metrics

    • PLANT_POWER_CONSUMPTION READ
    • PLANT_POWER_PRODUCTION READ
    • DAILY_PREDICTIONS READ
    • ENERGY_TYPE READ
    • PLANT_HEALTH READ

The exact set of permissions attached to a user depends on the roles configured in the Homsai backend.

Ownership checks​

For many operations on a specific plant (and its devices/sensors), the backend enforces ownership:

  • the caller must have the required permission (e.g. PLANTS UPDATE);
  • and must be the owner of the plant resource.

If a user has the generic permission but is not the owner of the target plant, the backend will typically respond with 403 Forbidden.

Security conventions for endpoints​

  • All read/write operations on plants, devices, sensors, metrics, and forecasts require:

    • a valid JWT accessToken;
    • the appropriate permission(s);
    • and, where applicable, plant ownership.

  • Some authentication endpoints are public:

    • POST /auth/login
    • POST /auth/resetPassword (to request a password reset email)

  • Some setup endpoints require a special JWT context:

    • POST /auth/setPassword (typically used for first‑time password setup after an invitation).

If the token is missing or invalid, the backend returns 401 Unauthorized.
If the token is valid but the user lacks the necessary permission or ownership, the backend returns 403 Forbidden.

Practical examples​

  • Listing plants

    • Endpoint: GET /plants
    • Requirements: valid accessToken + PLANTS READ

  • Updating a plant

    • Endpoint: PUT /plants/{plantUuid}
    • Requirements: valid accessToken + PLANTS UPDATE + caller is owner of the plant

  • Reading consumption metrics

    • Endpoint: GET /plants/{plantUuid}/daily-power-consumptions
    • Requirements: valid accessToken + PLANT_POWER_CONSUMPTION READ + plant ownership

Clients should handle:

  • token renewal via GET /auth/token when receiving 401 errors due to expired access tokens;
  • permission/ownership issues (403) by checking user roles and plant assignments in the Homsai platform.