Organizations

Xentree supports organization management for collaborative workspaces.

What you can do

create and manage organizations

assign roles to members

invite or remove users

structure collaboration across teams

Authentication and scopes

Organizations endpoints support both bearer and API key auth.

Recommended API key scopes:

organizations:read for listing organizations and members

organizations:write for create/update/delete and membership changes

Main endpoints

POST /api/organizations

GET /api/organizations

GET /api/organizations/{org_id}

PATCH /api/organizations/{org_id}

DELETE /api/organizations/{org_id}

Members

GET /api/organizations/{org_id}/members

POST /api/organizations/{org_id}/members

PATCH /api/organizations/{org_id}/members/{target_user_id}

PUT /api/organizations/{org_id}/members/{target_user_id}

DELETE /api/organizations/{org_id}/members/{target_user_id}

Organization object

GET /api/organizations, GET /api/organizations/{org_id}, POST /api/organizations, and PATCH /api/organizations/{org_id} return:

Field	Type	Description
`id`, `name`, `slug`, `description`, `is_active`		Core organization fields
`role`	string, nullable	The caller's role in this organization
`joined_at`	datetime, nullable	When the caller joined
`is_internal`	boolean	Internal Xentree organization flag
`members_count`	integer, nullable	Number of members
`teams_count`	integer, nullable	Number of teams
`custom_domain_entitlement`	boolean	Whether custom domains are enabled. See Subscriptions and Entitlements
`connect_entitlement`	boolean	Whether Xentree Connect is enabled
`custom_domain`	string, nullable	Configured customer hostname
`custom_domain_verification_status`	string	DNS verification state
`custom_domain_ssl_status`	string	SSL certificate state
`custom_domain_cname_target`	string, nullable	CNAME target to point DNS at
`cf_custom_hostname_id`	string, nullable	Cloudflare custom hostname ID

See Custom Domains for the custom_domain_* workflow.

Update an organization

PATCH /api/organizations/{org_id} accepts a JSON body where every field is optional. Send only what you want to change:

{
  "name": "Acme Learning",
  "description": "Workspace for team learning",
  "is_active": true
}

name: 1–100 characters

description: string or null

is_active: boolean

Returns the updated organization object.

Webhooks

Organization administrators on a Team plan can subscribe to events. See Webhooks.

Role model

Representative roles include:

administrator

billing_manager

team_manager

member

Member API details

List members

GET /api/organizations/{org_id}/members

Optional query: team_id to filter members in a specific team.

Response includes scoped team fields per organization:

team_id

team_name

Update role only

PATCH /api/organizations/{org_id}/members/{target_user_id}

Super admins are resolved from auth context (JWT/session) and are not restricted by per-row organization role.

Regular administrators can update role in the same organization.

Team managers cannot use this endpoint to elevate roles.

Comprehensive update (role/org/team)

PUT /api/organizations/{org_id}/members/{target_user_id}

Supports combined update:

role

organization_id

team_id (null to remove team assignment)

Permission order:

super admin: full access

organization administrator: full access in allowed org scope

team manager: team assignment only

Team assignment is validated against destination organization to avoid cross-organization mismatches.

Example create organization request

{
  "name": "Acme Learning",
  "slug": "acme-learning",
  "description": "Workspace for team learning and collaboration"
}

Access model

Most organization endpoints require an authenticated user, and privileged actions require the appropriate organization role.

When using API keys, organization-role checks still apply after scope checks.

Organizations

What you can do#

Authentication and scopes#

Main endpoints#

Organizations#

Members#

Organization object#

Update an organization#

Webhooks#

Role model#

Member API details#

List members#

Update role only#

Comprehensive update (role/org/team)#

Example create organization request#

Access model#

What you can do

Authentication and scopes

Main endpoints

Organizations

Members

Organization object

Update an organization

Webhooks

Role model

Member API details

List members

Update role only

Comprehensive update (role/org/team)

Example create organization request

Access model