Concepts
Permission domains and scopes
Every permission is a pair: a domain (what area) and a scope (whose data).
Each domain has three scopes:
_TENANT (the whole organization), _PARENT_LOCAL (one chapter and every chapter below it) and _LOCAL (one chapter). So HR_LOCAL means “manages people for one chapter” and FINANCIAL_TENANT means “manages money for the whole organization”. Some permissions imply others; the full matrix is in Permissions.
ADMIN_TENANT satisfies every permission check. Granting it is not the same as making someone an Orgo administrator: the account flag that unlocks the configuration screens and several endpoints (such as creating roles and webhooks) is separate. See Permissions.
Where local centers fit
ALocalCenter is a kind of Unit. A unit is the generic grouping primitive: local centers, role groups (automatic membership by criteria), and groups. A role assignment attaches a person to a unit, which for chapter roles is the local center itself.
Step 1: Create a local center
Creating a local center needs organization-wide HR rights.isActive: false hides a center from new-member registration while keeping it visible to admins. Other fields include parent and isParent (hierarchy, step 6), region, currency, website, social URLs, bank account fields and whoCanCreateEvents. The response carries the integer id used in /api/v1/local_centers/{id} and, as a unit, in /api/v1/units/{id}.
Step 2: Create a role
A role is a named position (“Chapter Lead”, “Treasurer”, “Outreach Coordinator”) that can carry permissions. Create one per distinct responsibility. This needs an Orgo administrator.permissions is the array of permission constants the role grants; they are the values documented in Permissions. Roles live at the organization level and are reusable across centers. Other fields: namePlural, unitType, position (ordering), isNational, isLocalCenterParent, isUserType (the role is a member type), isVolunteer, isNotEligibleForFee. Changing a role’s permissions later recalculates the permissions of the people who hold it (done inline for up to 300 holders, asynchronously for more).
Step 3: Assign the role to a person, scoped to a unit
Scoping happens at assignment time. The same role can be assigned to different people at different units.isAdmin needs group admin or organization-wide HR rights. Other fields: dateEnded (end it on a date) and localCenterPermission (extra chapters, when the organization uses multi-center access).
Assignments stack. A person can be Chapter Lead in Boston, Outreach Coordinator in Manchester and Treasurer at the organization level: three separate UserRole records. The assignment also creates a follow relationship for the person.
To replace all of a person’s roles in one call, send the full list to PATCH /api/v1/users/{id}/update-roles as rawUserRoles entries shaped roleId_unitId (and optionally userType). Orgo compares it with the person’s active roles, adds and ends the difference, creates notifications, and recalculates permissions. It needs HR rights over the person’s center.
Step 4: Audit who has what
Who holds roles at this center?
hydra:totalItems gives the count. Without exists[dateEnded]=false, ended assignments are included too. Other filters: role, role.isLocalCenter, role.isNational, user.status.
Every assignment for one person
The org chart
user_roles.
Step 5: Revoke
Delete the assignment:PATCH /api/v1/user_roles/{id} with a dateEnded. The member’s account is untouched; they only lose the permissions that role granted. A permission check is evaluated on each request, so revocation applies on the person’s next request, but a session they already hold is not ended.
Step 6: Restructure the hierarchy
For federations with regions (“Northeast Region” containing Boston, New York, Philadelphia), set a parent on each child center:_PARENT_LOCAL permission anchored at the parent (Northeast Region) can then act on all centers below it, at any depth, without a _LOCAL grant on each. Deleting a center needs ADMIN_TENANT.
Step 7: Self-service join for groups
Groups (not local centers) can be opened for members to join themselves. For a group marked joinable:400 You are already part of this group, and a group that is not joinable, or belongs to another organization, answers 400 You are not allowed to join the group.
Common gotchas
The user has ADMIN_TENANT but a settings call still fails
The user has ADMIN_TENANT but a settings call still fails
ADMIN_TENANT passes every permission check, but configuration endpoints and screens (roles, webhooks, single sign-on) additionally require the Orgo administrator account flag, which is set separately on the member’s Permissions tab. See Permissions.A local center cannot be removed
A local center cannot be removed
Deleting a center that still has active members or related data does not remove it: it is closed instead (status
CLOSED, with an end date). A center with nothing attached is deleted for good. To fully wind one down, move members to another center first (PATCH /api/v1/users/{id} with a new localCenter).Parent permissions don't cascade
Parent permissions don't cascade
Regional permissions follow the center hierarchy, so check that each child center has its
parent set (step 6) and that the person’s permission is _PARENT_LOCAL, anchored at the parent. A _LOCAL grant never cascades.How do I give one role to every member of a chapter?
How do I give one role to every member of a chapter?
Two options. Automatic role groups (
POST /api/v1/role_groups) add and remove members from a unit by criteria such as roles, region, age, gender, full-member status and fee level. Or loop on your side: page through GET /api/v1/users?localCenter=4 and POST one user_roles per person. There is no bulk role-assignment endpoint, because each assignment has its own notifications and permission recalculation.What to do next
- Permissions: the full domain and scope matrix
- Onboard a new member: the application side of getting members into a center
- Tenancy: how tenant isolation interacts with center scoping

