Skip to main content
Plans: Pro and Enterprise. Self-hosted: Enterprise license.
On Individual, reads stay open, but writes to org units, org users, and directory sync return 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:
Below the role floor, reads don’t fail. A caller below 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:
Errors carry "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.
Sorted by username. total counts every match, not just this page.

Change a role

PUT /api/org/users/{id}/role
A 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.