Authentication and access

Every data endpoint requires a Bearer token, and what your account can call is set by its subscription. This page covers both, plus the error responses you should handle.

Account provisioning

API accounts are created and managed by the SolarSENS team — there is no self-service signup. Email support@solarsens.co with the IP address(es) your integration will call from; the API only accepts requests from IPs registered to your account. The same channel handles plant access changes, subscription changes, and credential resets.

Token lifecycle

Token	Lifetime	How to get it
Access token	1 hour	POST /login/access-token (form fields username, password)
Refresh token	7 days	Returned alongside the access token
Non-expiring token	Until replaced	POST /login/non-expiring-token (authenticated)

Send the access token on every data request:

Authorization: Bearer <access_token>

Refreshing

When the access token expires (responses turn 401 {"detail": "Token has expired"}), exchange the refresh token for a new pair instead of logging in again. The refresh token is passed as a query parameter:

curl -X POST "https://www.public.solarsens.co:8443/ava/public/api/v1/login/refresh-token?refresh_token=$REFRESH_TOKEN"

The response has the same shape as login: a fresh access_token and refresh_token. An invalid or expired refresh token returns 400 {"detail": "Invalid refresh token"} — at that point, log in again with credentials.

Non-expiring tokens

For server-to-server integrations that cannot manage hourly refresh, generate a non-expiring token while authenticated:

# Generate (replaces any previous non-expiring token)
curl -X POST "https://www.public.solarsens.co:8443/ava/public/api/v1/login/non-expiring-token" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Fetch the current one
curl "https://www.public.solarsens.co:8443/ava/public/api/v1/login/non-expiring-token" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The token is used exactly like an access token. Each account holds one non-expiring token at a time; GET returns 404 {"detail": "Non-Expiring Token not found."} if none has been generated. Treat it like a password — it stays valid until replaced, and SolarSENS can revoke it on request.

Subscription tiers

Your subscription tier determines which endpoint families your account can call:

Tier	/data/portfolio/*	/data/plant/*
Portfolio	Yes	No
Plant	Yes	Yes
Device	Yes	Yes

Independent of tier, each account sees only its own plants: GET /data/plant/list returns exactly the plants you can query, and requests for any other plant_id return 403. Newly added plants and metadata changes appear in the plant list after the daily refresh; contact support if a new plant needs to be available sooner.

Error responses

Errors return a JSON body with a detail field.

Status	Meaning	Typical detail
400	Bad credentials or invalid refresh token	"Invalid refresh token"
401	Missing, invalid, or expired token	"Token has expired"
403	No valid subscription, wrong tier, or plant outside your account	"Access to the Plant/Devices is forbidden."
404	Resource not found	"Non-Expiring Token not found."
422	Malformed JSON request body	Validation object describing the parse error
500	Server error	"An error occurred: ..." — contact support if it persists

Request volume terms are set per account; contact support@solarsens.co if you expect high call rates.