Organizational Units API
Reference for the Organizational Units endpoint group — 7 endpoints.
Generated from the live OpenAPI spec. Re-run _generate_api_reference.py after backend changes.
Authentication#
All endpoints require a Bearer JWT in the Authorization header unless noted otherwise. See Concepts → Tokens and scopes and Reference → OAuth endpoints for how to obtain one.
Endpoints#
GET /api/v1/tenants/{tenant_id}/ous#
List Ous
List organizational units in the tenant.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
page |
query | no | integer |
|
per_page |
query | no | integer |
|
search |
query | no | string | null |
|
parent_id |
query | no | string | null |
Responses:
| Status | Body |
|---|---|
200 |
application/json → PaginatedResponse_OUListItem_ |
422 |
application/json → HTTPValidationError |
POST /api/v1/tenants/{tenant_id}/ous#
Create Ou
Create a new organizational unit.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
Request body:
Required.
application/json→OUCreate
Responses:
| Status | Body |
|---|---|
201 |
application/json → ApiResponse_OUResponse_ |
422 |
application/json → HTTPValidationError |
GET /api/v1/tenants/{tenant_id}/ous/tree#
Get Ou Tree
Get organizational units as a tree structure.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_list_OUTreeNode__ |
422 |
application/json → HTTPValidationError |
DELETE /api/v1/tenants/{tenant_id}/ous/{ou_id}#
Delete Ou
Delete an organizational unit.
strategy:
- BLOCK: Fail if has users or child OUs
- MOVE_UP: Move users and child OUs to parent
- CASCADE: Delete child OUs (users moved to parent)
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
ou_id |
path | yes | string |
|
strategy |
query | no | string |
Responses:
| Status | Body |
|---|---|
204 |
Successful Response |
422 |
application/json → HTTPValidationError |
GET /api/v1/tenants/{tenant_id}/ous/{ou_id}#
Get Ou
Get an organizational unit by ID.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
ou_id |
path | yes | string |
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_OUResponse_ |
422 |
application/json → HTTPValidationError |
PATCH /api/v1/tenants/{tenant_id}/ous/{ou_id}#
Update Ou
Update an organizational unit.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
ou_id |
path | yes | string |
Request body:
Required.
application/json→OUUpdate
Responses:
| Status | Body |
|---|---|
200 |
application/json → ApiResponse_OUResponse_ |
422 |
application/json → HTTPValidationError |
GET /api/v1/tenants/{tenant_id}/ous/{ou_id}/users#
List Ou Users
List users in an organizational unit.
Parameters:
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | yes | string |
|
ou_id |
path | yes | string |
|
page |
query | no | integer |
|
per_page |
query | no | integer |
|
include_nested |
query | no | boolean |
Responses:
| Status | Body |
|---|---|
200 |
application/json → PaginatedResponse |
422 |
application/json → HTTPValidationError |
Schemas#
Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.
ApiResponse_OUResponse_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
OUResponse |
yes | |
meta |
MetaResponse |
no |
ApiResponse_list_OUTreeNode__#
| Field | Type | Required | Description |
|---|---|---|---|
data |
array of OUTreeNode |
yes | |
meta |
MetaResponse |
no |
HTTPValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
detail |
array of ValidationError |
no |
MetaResponse#
Metadata included in API responses.
| Field | Type | Required | Description |
|---|---|---|---|
request_id |
string | null |
no | |
timestamp |
string (date-time) |
no |
OUChildInfo#
Child OU info.
| Field | Type | Required | Description |
|---|---|---|---|
ou_id |
string |
yes | |
name |
string |
yes | |
path |
string |
yes | |
user_count |
integer |
no | Default: 0 |
children |
array of OUChildInfo |
no |
OUCreate#
Schema for creating an OU.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
yes | |
description |
string | null |
no | |
parent_id |
string | null |
no | |
custom_attributes |
object | null |
no |
OUListItem#
Abbreviated OU info for lists.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
yes | |
name |
string |
yes | |
path |
string |
yes | |
parent_id |
string | null |
no | |
user_count |
integer |
no | Default: 0 |
OUResponse#
Full OU response.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
yes | |
description |
string | null |
no | |
id |
string |
yes | |
path |
string |
yes | |
parent_id |
string | null |
no | |
child_ou_count |
integer |
no | Default: 0 |
user_count |
integer |
no | Default: 0 |
children |
array of OUChildInfo | null |
no | |
custom_attributes |
object | null |
no | |
created_at |
string (date-time) |
yes | |
updated_at |
string (date-time) | null |
no |
OUTreeNode#
Tree node for OU hierarchy.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string |
yes | |
name |
string |
yes | |
path |
string |
yes | |
children |
array of OUTreeNode | null |
no |
OUUpdate#
Schema for updating an OU.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | null |
no | |
description |
string | null |
no | |
parent_id |
string | null |
no | |
custom_attributes |
object | null |
no |
PaginatedResponse#
Paginated API response wrapper.
| Field | Type | Required | Description |
|---|---|---|---|
data |
array of any | yes | |
pagination |
PaginationMeta |
yes | |
meta |
MetaResponse |
no |
PaginatedResponse_OUListItem_#
| Field | Type | Required | Description |
|---|---|---|---|
data |
array of OUListItem |
yes | |
pagination |
PaginationMeta |
yes | |
meta |
MetaResponse |
no |
PaginationMeta#
Pagination metadata.
| Field | Type | Required | Description |
|---|---|---|---|
page |
integer |
yes | |
per_page |
integer |
yes | |
total_items |
integer |
yes | |
total_pages |
integer |
yes |
ValidationError#
| Field | Type | Required | Description |
|---|---|---|---|
loc |
array of string | integer |
yes | |
msg |
string |
yes | |
type |
string |
yes |