# 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](/developers/mcp/tools). 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](/developers/mcp/authorization#7-more-permissions-later)).

### 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."