Skip to main content
This walkthrough sets up organizational structure: a new local center (chapter, branch, regional office), the roles that run it, and the assignments that scope what each person can do. It uses the LocalCenter, Unit, Role and UserRole resources. Who is this for: enterprise-onboarding integrations that build structure programmatically, federation tools that sync org-chart changes from an upstream system, and admin dashboards that audit permissions in bulk.

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

A LocalCenter 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.
This makes James Patterson “Chapter Lead” for the Boston center only. Who may make an assignment depends on the unit: a local center needs HR rights over that center, a role group needs organization-wide HR rights or being a group admin, and a group needs a group admin. Setting 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?

The answer lists each assignment with the user, role and dates; 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

Useful for “show everything James can do” before revoking.

The org chart

Returns assignments shaped for an org chart, 100 per page, with the same filters as user_roles.

Step 5: Revoke

Delete the assignment:
This needs HR rights over the unit’s center (organization-wide HR bypasses the check). To keep history instead, 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:
Anyone holding a _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:
This is called as the member who is joining, with their session. It adds a plain membership (no role and no admin flag). A repeat answers 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

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.
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).
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.
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