Members¶

Members and users are distinct concepts. A member refers to a participant in the community, such as the owner of a resource or meter. A user is the entity in the database itself that is registered on the platform.

Role Hierarchy¶

graph TD
    SU[SUPER_USER] -->|Creates Communities & Manages Deployment| A[ADMIN]
    A -->|Manages Community| MB[MEMBER]

Role	Scope	Permissions
`SUPER_USER`	Platform	Manages every aspect of the platform and is the only role authorised to create new communities.
`ADMIN`	Community	Manages every aspect of the community it manages, including its members, meters, resources, sessions, and energy configuration
`MEMBER`	Own data	May have access (depending on email verification) to the member dashboard, where they can only view their own data and overall community-aggregated information

Community creation

Only SUPER_USER accounts can create new communities via POST /communities. ADMIN users have full CRUD access within the communities they manage but cannot create or delete communities themselves.

Member dashboard access

A MEMBER can only access the member dashboard after verifying their email address. Unverified members have no access. Once verified, they can see:

Their own meter measurements and settlement results
Community-aggregated data (total generation, consumption, savings)
Their own transaction history

Members cannot see other members' private data (individual loads, measurements, etc.).

User–Community Association¶

A user can belong to multiple communities with a different role in each. The UserCommunityAssociation links a user to a community with a specific role.

graph LR
    U[User] -->|role: ADMIN| C1[Community A]
    U -->|role: MEMBER| C2[Community B]

Membership Validity¶

A user's membership in a community is dated. The membership fields below are versioned, so the same user can be active, then inactive, then active again in one community without creating a new user:

Field	Required	Description
`status`	—	`ACTIVE` or `INACTIVE` for this period
`role`	—	Community role (`MEMBER` or `ADMIN`) for this period
`is_host`	—	Anchor/Host flag for this period
`is_promoter`	—	Promoter flag for this period
`start_date`	✅	First day (inclusive, Europe/Lisbon) of this membership period
`end_date`	—	Last day (inclusive) of this membership period. `null` = open-ended

The user's profile (name, email, phone, address, NIF, login) is not dated and always shows its current value.

POST /communities/{community_id}/users and PUT /communities/{community_id}/users/{user_id} require start_date.
GET /communities/{community_id}/members?effective_at=YYYY-MM-DD lists the members on that day. Without effective_at, today is used.
DELETE /communities/{community_id}/users/{user_id}?effective_at=YYYY-MM-DD ends the membership from that day. The user account is not deleted.

See Business Validity for the full rules.

Authentication Flow¶

The platform uses Keycloak-issued Bearer tokens. Each API request is validated against the role embedded in the token, as well as the user's community-specific role stored in the database.

Role in token vs. community role

The JWT carries the platform role (SUPER_USER, USER). Community-specific roles (ADMIN, MEMBER) are stored in the database and checked separately for each community-scoped endpoint.

Permission Summary¶

Action	SUPER_USER	ADMIN	MEMBER
Create community	✅	❌	❌
Manage community settings	✅	✅	❌
Add / remove members	✅	✅	❌
Manage meters & resources	✅	✅	❌
Upload meter data	✅	✅	❌
Run market / settlement	✅	✅	❌
View community aggregated data	✅	✅	✅ (verified)
View own data	✅	✅	✅ (verified)
View other members' private data	✅	✅	❌