Organization Management - Cloosphere Guide

Admin › Users › Organizations

Organization management reflects your company’s department structure in Cloosphere to systematically control resource access.

Sync with Microsoft Entra ID (Azure AD), Keycloak, or Google Workspace, or build the org structure directly via JSON Import.

Organizational Hierarchy

Cloosphere’s organization system consists of hierarchical Organizations and Organizational Units.

Concept	Description	Example
Organization	Top-level entity. Identified by tenant ID and domain	”Cloocus Inc.”
Organizational Unit (OU)	Sub-units like departments, teams. Hierarchically nestable	”Engineering > Backend Team”
Members	List of users belonging to an OU	user_id array

Organizational Unit Types

OUs distinguish purpose via the type field.

Type	Description
department	Department (division-level upper organization)
team	Team (working-unit organization)
group	Group (functional unit, e.g., project team)

In the current production environment, most observed organizational units are of type department.

Organizations vs Groups

Cloosphere offers two user grouping mechanisms — groups and organizations. Use them appropriately by purpose.

Aspect	Group	Organization
Purpose	Permission management	Reflect organizational structure
Structure	Flat (no hierarchy)	Tree (hierarchical)
Permission setup	Permissions assigned directly to the group	Specify OU in resource’s access_control
External integration	Manual management	Auto-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:

Method	Description
Microsoft Graph	Auto-sync organizational structure from Entra ID (Azure AD)
Keycloak	Sync from Keycloak groups/organizations
Google Workspace	Sync from Google Workspace directory
JSON Import	Upload 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 Variable	Description
`MICROSOFT_CLIENT_ID`	Azure App Registration’s Client ID
`MICROSOFT_CLIENT_SECRET`	Client Secret
`MICROSOFT_CLIENT_TENANT_ID`	Azure AD Tenant ID

Running Sync

Open the sync dialog

Click the sync button () next to the search box at the top-right of the organization list to open the Organization Sync dialog.

Pick a data source

In the Data Source dropdown, pick the sync method — JSON Import (default) · Microsoft Graph · Keycloak · Google Workspace. For Entra ID integration, pick Microsoft Graph.When Microsoft Graph is selected, choose which items to fetch.

Option	Description	Default
Administrative Units	Entra ID’s org management feature; suited to hierarchies	ON
Security Groups	Use security groups as organizational units; filter with OData query	OFF
Departments	Auto-extract department names from user profiles	OFF

The Group Filter box appears only while Security Groups is on. Enter an OData filter expression to import specific groups only (optional).

Microsoft Graph sync options — Sync options when Data Source = Microsoft Graph

Run sync

Click the Sync button at the bottom of the dialog.

Organization Sync dialog — data source selection (default: JSON Import)

Verify results

Verify the synced OU tree and member mapping. On success the dialog reports counts as Synced N organization(s), M unit(s); if nothing was found, it suggests enabling different options.

Options for the other data sources

Switching Data Source to Keycloak or Google Workspace changes the option set as well.

Keycloak
Google Workspace

The server URL and credentials are not entered on screen — they come from the OPENID_PROVIDER_URL · OAUTH_CLIENT_ID · OAUTH_CLIENT_SECRET environment variables.

Option	Description	Default
Groups	Sync the Keycloak group hierarchy as organizational units	ON
Organizations (v26+)	Use the Keycloak Organizations feature (requires Keycloak 26 or later)	OFF

Option	Description	Default
Organizational units (OU)	Import the Google Workspace OU hierarchy	ON
Groups	Import Google Groups as organizational units	OFF

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 Level	Description
Read	OU members can view/use the resource
Write	OU 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

Resource	Access Control	Description
HR Policy KB	HR Team OU (Read)	Only HR team can view HR policy
Sales Agent	Sales Division OU (Read)	Entire Sales department can use
Sales DB	Operations Division OU (Read)	Only Operations department queries sales data
Company-wide Notice KB	Top-level OU (Read)	Entire organization can access

Viewing the OU List

Selecting an organization expands its organizational units below, in hierarchy order.

Element	Description
Indentation	Mirrors hierarchy depth — the deeper the OU, the further right it sits
Type badge	Grey badge to the right of the name (`department` · `team` · `group`)
Member-count button	People icon + number. Click it to open that OU’s member list
Type tabs	`All / Department / Team / Group` tabs appear above the list only when two or more types exist

The member list shows both members mapped by IdP sync and users auto-assigned via OAuth login; members without a Cloosphere account yet are marked Not registered.

Per-Organization Usage Limits

Per-OU token caps are managed under Admin > Settings > Models, not on the Organizations screen. They are set per model — there is no single cap that applies to an OU as a whole.

Turn usage limits on

Under Admin > Settings > Models, click the Token Limit button at the top to open the Token Limit Management dialog. Turn on Enable Usage Limit, and optionally set the default daily token limit and the action on exceeding (Warn / Block).

Expand a model

Once usage limits are on, each model row becomes expandable. Expanding shows that model’s base limit along with three override cards.

Set the org unit override

Among User overrides · Group overrides · Org unit overrides, open Org unit overrides and set per-OU caps. The number on each card is the count of overrides currently registered.

Value	Meaning
Empty	Inherit — decided by a higher layer
0	Explicitly unlimited
Positive number	Daily token cap

Usage limits can be set at four layers — global, user, group, and organizational unit. When several layers carry a value, the most permissive (highest) one applies, and if any layer is 0 (unlimited) that wins immediately. Overrides are designed to raise a cap, so you cannot shrink a higher-layer cap by entering a smaller value at a lower layer.

Per-OU Guardrails

A screen for attaching guardrails directly to an organizational unit is not available in the current release. OU rows carry only the member-count button.

Apply guardrails through these paths instead.

Target	Where to configure
Per group	Admin > Users > Groups & Permissions > edit a group > `Chat Guardrail` on the General tab
Per agent	Workspace > Agents > that agent’s guardrail settings
Global (AI coding tools)	The `Security` section of Admin > Settings > Code Gateway

If you need guardrails at department granularity, map the OU to a group (see Group ↔ OU Mapping) and set the chat guardrail on that group — that is the route available today.

Deleting an Organization

The bottom of the Organizations screen has a Delete Organization area.

Deleting removes the organization and every organizational unit under it, permanently. This cannot be undone. Confirm the organization name in the dialog before proceeding. Member associations are removed as well — user accounts themselves are not deleted.

Sync Provider List

The four currently supported sync providers:

Provider	Description	Requirements
JSON Import	Direct configuration via JSON data	None
Microsoft Graph	Auto-sync from Entra ID (Azure AD)	`MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_CLIENT_TENANT_ID`
Keycloak	Sync from Keycloak groups/organizations	`OPENID_PROVIDER_URL`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`
Google Workspace	Sync from Google Workspace directory	`GOOGLE_ADMIN_SERVICE_ACCOUNT_KEY`, `GOOGLE_ADMIN_IMPERSONATE_EMAIL`

FAQ

Organization sync fails

Verify Azure App Registration has Directory.Read.All permission.
Verify environment variables MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_CLIENT_TENANT_ID are correctly set.
Check server logs for detailed error messages.

Do I need to use both organizations and groups?

Not necessarily. Permission management alone is fine with groups. Use organizations additionally when you need department-based access control with Entra ID integration.

Are members deleted when I delete an OU?

Deleting an OU doesn’t delete the user accounts in it. Only the resource access permissions configured for that OU are removed.

User Management

User list, roles/groups, permission settings

Groups & Permissions

Map OUs to groups to apply permissions and chat guardrails

Usage

Usage and cost monitoring by organization and user

Deployment Checklist

OIDC environment variables required for Keycloak/Entra sync

​Organizational Hierarchy

​Organizational Unit Types

​Organizations vs Groups

​Creating Organizations

​Microsoft Entra ID Sync

​Prerequisites

​Running Sync

​Options for the other data sources

​JSON Import

​Organization-based Access Control

​Setting OU Permissions on Resources

​Permission Inheritance

​Example Use

​Viewing the OU List

​Per-Organization Usage Limits

​Per-OU Guardrails

​Deleting an Organization

​Sync Provider List

​FAQ

​Related Pages

User Management

Groups & Permissions

Usage

Deployment Checklist

Organizational Hierarchy

Organizational Unit Types

Organizations vs Groups

Creating Organizations

Microsoft Entra ID Sync

Prerequisites

Running Sync

Options for the other data sources

JSON Import

Organization-based Access Control

Setting OU Permissions on Resources

Permission Inheritance

Example Use

Viewing the OU List

Per-Organization Usage Limits

Per-OU Guardrails

Deleting an Organization

Sync Provider List

FAQ

Related Pages