Skip to main content
Organization management reflects your company’s department structure in Cloosphere to systematically control resource access. Sync with Microsoft Entra ID (Azure AD), or build the org structure directly via JSON Import.
Organization management screen

​
Organizational Hierarchy

Cloosphere’s organization system consists of hierarchical Organizations and Organizational Units.
ConceptDescriptionExample
OrganizationTop-level entity. Identified by tenant ID and domain”Cloocus Inc.”
Organizational Unit (OU)Sub-units like departments, teams. Hierarchically nestable”Engineering > Backend Team”
MembersList of users belonging to an OUuser_id array

​
Organizational Unit Types

OUs distinguish purpose via the type field.
TypeDescription
departmentDepartment (division-level upper organization)
teamTeam (working-unit organization)
groupGroup (functional unit, e.g., project team)

​
Organizations vs Groups

Cloosphere offers two user grouping mechanisms — groups and organizations. Use them appropriately by purpose.
AspectGroupOrganization
PurposePermission managementReflect organizational structure
StructureFlat (no hierarchy)Tree (hierarchical)
Permission setupPermissions assigned directly to the groupSpecify OU in resource’s access_control
External integrationManual managementAuto-sync with Entra ID
Use case”Grant agent creation permission""HR team only accesses HR Policy KB”
Use groups for permission control (what they can do) and organizations for access control (what they can see). The two systems can be used together.

​
Creating Organizations

Organizations and OUs are created only via sync. There’s no UI to create them manually. Supported sync methods:
MethodDescription
Microsoft GraphAuto-sync organizational structure from Entra ID (Azure AD)
JSON ImportUpload JSON data to construct the org structure
See Microsoft Entra ID Sync and JSON Import below for details.

​
Microsoft Entra ID Sync

Sync organizational structure automatically with Microsoft Entra ID (Azure AD).

​
Prerequisites

Microsoft OAuth setup is required for Entra ID sync. Set the following environment variables on the server.
Environment VariableDescription
MICROSOFT_CLIENT_IDAzure App Registration’s Client ID
MICROSOFT_CLIENT_SECRETClient Secret
MICROSOFT_CLIENT_TENANT_IDAzure AD Tenant ID

​
Running Sync

1

Pick sync options

Pick which data sources to fetch during sync.
OptionDescriptionDefault
Administrative UnitsFetch Entra ID Administrative UnitsON
Security GroupsFetch Entra ID Security GroupsOFF
DepartmentsBuild from user department infoOFF
Group FilterFilter to specific groups (optional)-
2

Run sync

Click the Sync button.
3

Verify results

Verify the synced OU tree and member mapping.
Entra ID sync options

​
JSON Import

In environments without Entra ID, import the org structure via JSON data directly. 
{
  "organization": {
    "tenant_id": "my-company",
    "name": "My Company",
    "domain": "mycompany.com"
  },
  "units": [
    {
      "id": "dept-1",
      "name": "Engineering",
      "type": "department",
      "children": [
        { "id": "team-1", "name": "Backend Team", "type": "team" },
        { "id": "team-2", "name": "Frontend Team", "type": "team" }
      ]
    }
  ]
}

​
Organization-based Access Control

Use OUs to control resource (agents, KBs, databases, etc.) access scope.

​
Setting OU Permissions on Resources

In each workspace resource’s Access settings, specify the OU.
Access LevelDescription
ReadOU members can view/use the resource
WriteOU members can edit the resource

​
Permission Inheritance

Permissions granted to upper OUs are inherited by lower OUs.
When resource access is set on an upper OU, all members of lower OUs automatically receive the same permission.

​
Example Use

ResourceAccess ControlDescription
HR Policy KBHR Team OU (Read)Only HR team can view HR policy
Sales AgentSales Division OU (Read)Entire Sales department can use
Sales DBOperations Division OU (Read)Only Operations department queries sales data
Company-wide Notice KBTop-level OU (Read)Entire organization can access

​
Per-OU Resource Permission View

Admins can view all resource permissions assigned to a specific OU at a glance.
Per-OU resource permission list
Resource TypeItems Shown
Knowledge BaseName, Read/Write, inheritance
ToolsName, Read/Write, inheritance
PromptsName, Read/Write, inheritance
ModelsName, Read/Write, inheritance
DatabaseName, Read/Write, inheritance
GlossaryName, Read/Write, inheritance

​
Per-Organization Usage Limits

In the OU detail panel, set daily token limits.
SettingDescription
Daily token limitDaily token cap for users belonging to this OU (0 = unlimited)
This feature requires admin settings to have usage limits (enable_usage_limit) enabled.
Usage limits can be set at four levels — global, user, group, organization. When set at multiple levels, the most permissive (highest) value applies.

​
Per-OU Guardrails

Connect guardrails to OUs to auto-validate AI inputs/outputs of users in that OU. Configure in the Guardrail Settings of the OU detail panel.
SettingDescription
Pick guardrailsList of guardrails to apply to this OU (multi-select)
Inherit global guardrailsWhen on, also apply global (Code Gateway) guardrails. When off, only the OU-specified guardrails apply

​
Application Priority

Guardrails can be set at multiple levels — to users, the sum across all levels is applied. 
Agent guardrail   ─┐
Group guardrail   ─┼─  All combined and applied
OU guardrail      ─┤
Global guardrail  ─┘  (when global inheritance is on)
Global guardrails are configured in Admin > Code Gateway. Turning off Inherit global guardrails for an OU exempts it from global guardrail influence.

​
Sync Provider List

Currently supported sync providers:
ProviderDescriptionRequirements
JSON ImportDirect configuration via JSON dataNone
Microsoft GraphAuto-sync from Entra IDMICROSOFT_CLIENT_ID, CLIENT_SECRET, TENANT_ID
Additional provider support (Okta, Google Workspace, etc.) is planned.

​
FAQ

  1. Verify Azure App Registration has Directory.Read.All permission.
  2. Verify environment variables MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_CLIENT_TENANT_ID are correctly set.
  3. Check server logs for detailed error messages.
Not necessarily. Permission management alone is fine with groups. Use organizations additionally when you need department-based access control with Entra ID integration.
Deleting an OU doesn’t delete the user accounts in it. Only the resource access permissions configured for that OU are removed.