Plans: Pro and Enterprise. Self-hosted: Enterprise license.
402 with code plan_feature_not_included. On a self-hosted open-source server, these routes aren’t served.
These routes back Access control in the dashboard. Behavioral guide: User and org management.
A superuser passes every check. Send the session token as
Authorization: Bearer <token>. A missing or invalid token returns 401:
manager gets 200 with {"available": false} from GET /api/org/users and GET /api/org/units, and a non-admin gets the same from GET /api/access-control/overview. Treat it as “not available to you”.
Out-of-scope units and users return 404, not 403, so a manager can’t probe the parts of the org they don’t lead.
Response envelope (org units)
The/api/org/units routes wrap every response, success or error, in one envelope:
"data": null, the HTTP status, and a message. Successful writes with nothing to return answer 200 with "data": null.
Org context
GET /api/org/context
Who you are in the org structure. Any signed-in user, about themselves.
Users in your scope
List users
GET /api/org/users
Users the caller can see: everyone for an admin; for a manager, people in their units and everyone beneath the units they lead.
total counts every match, not just this page.
Change a role
PUT /api/org/users/{id}/role
manager can act only on users in their scope whose current role is below manager, and can grant only member. An admin and a superuser aren’t limited by rank. Nobody can change their own role, and the last admin can’t be demoted. The user is signed out of every session. Demoting to member also clears them as lead of any unit.
Set manual placement
PUT /api/org/users/{id}/placement
Replaces the units a user is placed in by hand. Directory-synced placements are left as they are.
A
manager can place only users they can see, and only into units they lead or that sit beneath one they lead. The role doesn’t change.
Org units
List units
GET /api/org/units
An
admin sees every unit. A manager sees the units they lead and everything beneath them; with tree=true a led unit whose parent they can’t see becomes a top-level node.
Create a unit
POST /api/org/units
201:
Units created here are always
manual.
Delete a unit
DELETE /api/org/units/{id}
Without
cascade, a unit with child units is refused with 409: unit_has_children: <n> live child unit(s); pass ?cascade=true to delete the subtree. Grants on a deleted unit stop reaching anyone. Requires admin (403: requires an admin). 200 with org unit deleted successfully, or 404.
Appoint or clear a lead
PUT /api/org/units/{id}/lead
Appointing a
member makes them a manager. An admin keeps their role. The previous lead returns to member if they no longer lead any unit. 200 with unit lead updated successfully. 400 with no such user. 404 if the unit is outside your scope.
Members
GET /api/org/units/{id}/members
source is idp for a directory-synced membership and manual for one added in Nasiko. unit_id is the unit the person actually sits in, which differs from the requested unit with include_descendants.
POST /api/org/units/{id}/members
200 with <n> member(s) added successfully. 400 with one or more users do not exist.
DELETE /api/org/units/{id}/members/{user_id}
200 with member removed successfully. 404 with not a member of this unit. 409 when the membership came from your identity provider. Remove the person from the group there instead.
Access overview
GET /api/access-control/overview
The admin summary at the top of Access control → Org structure. admin or superuser; anyone else gets {"available": false}.
units lists top-level units with counts for their whole subtree. unassigned_users lists up to 50 unplaced users, newest first.
Identity provider
Provider card
GET /api/identity/provider
404 with {"error": "identity is not configured"} when SSO isn’t set up. 403 with {"error": "requires an admin"} below admin.
Reset organization data
POST /api/identity/provider/reset-org-data
Removes every directory-synced unit and membership for the active provider and resets the affected users, other than admins and superusers, to member. Manual units and memberships stay. SSO sign-in keeps working. The next directory sync or SCIM push recreates the structure.