Permissions and communities

Three things decide what an app can do in PorchQ, and all three must allow a call:

1. Scopes: the permissions the person granted the app, by area, reading and changing separate.
2. Communities: the ones the person ticked when they connected.
3. Role: the person’s role in the community a call names. An app never does more than the person could do in PorchQ.

Scopes

Scope	What it allows	Who can be granted it	Asked for today
community:read	See your communities, your role, announcements, events, ballots, amenities and surveys	Everyone	Yes
maintenance:read	See maintenance requests (residents: their own)	Everyone	Yes
messages:read	Read your message threads with management	Everyone	Not yet
documents:read	Read documents you can see in PorchQ	Everyone	Yes
people:read	See names, email addresses and units of residents you manage	Owners and managers	Yes
meetings:read	Read meeting notes and their summaries	Owners and managers	Yes
billing:read	See balances, statements and payments (residents: their own; staff: reports)	Everyone	Yes
community:write	Draft announcements and ballots; create and change events; RSVP, book amenities and vote	Everyone	Yes
maintenance:write	Submit requests and add notes; staff can change status and assign	Everyone	Yes
messages:write	Reply in your threads; staff can draft replies	Everyone	Not yet
documents:write	Add and update documents and their visibility	Owners and managers	Not yet
people:write	Invite people, approve or remove members, change roles below owner	Owners and managers	Not yet

The words in the second column are the ones PorchQ’s consent page shows the person. “Asked for today” marks the scopes PorchQ’s current tools use; PorchQ’s 401 asks for exactly those (community:read, community:write, maintenance:read, maintenance:write, documents:read, people:read, meetings:read, billing:read). The others are reserved for tools still to come and can be granted now.

Each tool names the one scope it needs; see the tool reference. A call without it is answered with 403 and error="insufficient_scope", naming the missing scope, so the app can ask for it (step-up).

Owner- and manager-only scopes

people:read, people:write, meetings:read and documents:write are never offered to someone who is only a resident. If every community a person ticks is one where they are a resident, those lines don’t appear on the consent page and aren’t granted, whatever the app asked for.

The older two scopes

Before area scopes, PorchQ had read and write. Tokens granted them keep working:

Older scope	Reads as
read	community:read, maintenance:read, messages:read, documents:read, people:read, meetings:read, billing:read
write	community:write, maintenance:write

An app that asks for read or write is shown and granted the area scopes they cover. New apps should ask for area scopes.

Allow changes

On the consent page, “Let the app make changes” is ticked by default. Unticked, the app is granted only the reading scopes it asked for: every tool that changes something answers 403.

Communities

• A person’s communities are those where they have a role, plus every community their management company runs if they are one of its owners or managers.
• A connection reaches only the communities ticked on the consent page. A call naming any other community, even one the person belongs to, is answered as if it didn’t exist (not_found).
• property_select lists the communities a connection reaches.
• Pass property_id on every call. Without it, a call is answered only when the connection reaches one community; otherwise the answer is property_required with the list of communities to choose from.
• To reach another community, the person connects again and ticks it.

Confirming changes

Under PorchQ’s rules, a change that reaches residents waits for the person who asked to confirm it in PorchQ. Today that’s creating or changing a calendar event residents can see.

• The tool answers at once with status: "awaiting_confirmation", a sentence for the person (“I’ve prepared the event in PorchQ. Nothing goes out until you confirm it there: …”) and confirmation.url.
• Nothing happens until the person opens that page, signed in to PorchQ, and chooses Confirm. Then PorchQ makes exactly the change the page showed. Cancel drops it.
• Only the person whose connection asked can confirm, and only while their role still allows the change. The link works once.
• It expires after 24 hours, or when the event starts if that’s sooner. If the event changed in PorchQ in the meantime, nothing is changed.
• The app isn’t told the outcome. It can read the calendar afterwards (events_list).

Roles

PorchQ’s roles are owner (a board member), manager (a community manager) and tenant (a resident). An owner or manager of a management company counts as a manager in every community the company runs. A membership with no role reaches nothing. Each call uses the person’s role in the community it names:

	Owners and managers	Residents
Maintenance requests	All of the community’s	Only the ones they submitted
Documents	All	Only those shared with residents
Events	All, staff-only included	Those their membership can see
Ballots	All	Those they are eligible for
Announcements	Published ones	Published ones
Resident directory, meeting summaries, billing status	Yes	No: the tool answers that it is for owners and managers
Draft announcements, create and change events	Yes	No
File a maintenance request	Yes, as staff	Yes, in their own name

A tool that a role can’t use answers with isError: true and “This action is available only to owner and manager roles.”