Organization Management

Overview

The Organization Management API provides endpoints for managing organizations (groups) within a tenant. You can manage organization hierarchy, membership, and organization-level access control.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/organizations`	List organizations
GET	`/api/admin/organizations/:id`	Get organization details
POST	`/api/admin/organizations`	Create organization
PUT	`/api/admin/organizations/:id`	Update organization
DELETE	`/api/admin/organizations/:id`	Delete organization
GET	`/api/admin/organizations/:id/members`	List members
POST	`/api/admin/organizations/:id/members`	Add member
DELETE	`/api/admin/organizations/:id/members/:userId`	Remove member
GET	`/api/admin/organizations/:id/hierarchy`	Get hierarchy

List Organizations

Retrieve a list of organizations within the tenant.

Endpoint

GET /api/admin/organizations

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 20, max: 100)
`cursor`	string	-	Pagination cursor
`search`	string	-	Search by name
`parent_id`	string	-	Filter by parent organization ID
`include_children`	boolean	-	Include child organizations

Request Example

curl -X GET "https://{tenant-domain}/api/admin/organizations" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "org_abc123",
      "name": "Engineering",
      "display_name": "Engineering Department",
      "description": "Engineering department",
      "parent_id": null,
      "member_count": 25,
      "created_at": 1705881600,
      "updated_at": 1705968000
    },
    {
      "id": "org_def456",
      "name": "Backend",
      "display_name": "Backend Team",
      "description": "Backend development team",
      "parent_id": "org_abc123",
      "member_count": 10,
      "created_at": 1705968000,
      "updated_at": 1706054400
    }
  ],
  "total": 15,
  "cursor": null
}

Get Organization Details

Retrieve detailed information for a specified organization.

Endpoint

GET /api/admin/organizations/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Organization ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/organizations/org_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "org_abc123",
  "name": "Engineering",
  "display_name": "Engineering Department",
  "description": "Engineering department",
  "parent_id": null,
  "parent": null,
  "children": [
    {
      "id": "org_def456",
      "name": "Backend",
      "display_name": "Backend Team"
    },
    {
      "id": "org_ghi789",
      "name": "Frontend",
      "display_name": "Frontend Team"
    }
  ],
  "member_count": 25,
  "metadata": {
    "cost_center": "CC-001",
    "location": "New York"
  },
  "created_at": 1705881600,
  "updated_at": 1705968000
}

Create Organization

Create a new organization.

Endpoint

POST /api/admin/organizations

Request Body

Field	Type	Required	Description
`name`	string	✓	Organization name (alphanumeric, hyphens, underscores)
`display_name`	string	✓	Display name
`description`	string	-	Description
`parent_id`	string	-	Parent organization ID
`metadata`	object	-	Custom metadata

Request Example

curl -X POST "https://{tenant-domain}/api/admin/organizations" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DevOps",
    "display_name": "DevOps Team",
    "description": "Infrastructure and DevOps",
    "parent_id": "org_abc123",
    "metadata": {
      "cost_center": "CC-003"
    }
  }'

Response Example

{
  "id": "org_xyz789",
  "name": "DevOps",
  "display_name": "DevOps Team",
  "description": "Infrastructure and DevOps",
  "parent_id": "org_abc123",
  "member_count": 0,
  "created_at": 1706140800
}

Update Organization

Update existing organization information.

Endpoint

PUT /api/admin/organizations/:id

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/organizations/org_abc123" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Engineering Division",
    "description": "Engineering division (updated)"
  }'

Delete Organization

Delete an organization.

Endpoint

DELETE /api/admin/organizations/:id

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/organizations/org_abc123" \
  -H "Authorization: Bearer {token}"

Response

Status code 204 No Content (no body)

List Members

Retrieve a list of members for a specified organization.

Endpoint

GET /api/admin/organizations/:id/members

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 20, max: 100)
`cursor`	string	-	Pagination cursor
`role`	string	-	Filter by organization role

Request Example

curl -X GET "https://{tenant-domain}/api/admin/organizations/org_abc123/members" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "user_id": "usr_member001",
      "email": "[email protected]",
      "name": "John Doe",
      "organization_role": "admin",
      "joined_at": 1705881600
    },
    {
      "user_id": "usr_member002",
      "email": "[email protected]",
      "name": "Jane Smith",
      "organization_role": "member",
      "joined_at": 1705968000
    }
  ],
  "total": 25,
  "cursor": "eyJ1c2VyX2lkIjoidXNyX21lbWJlcjAwMiJ9"
}

Add Member

Add a member to an organization.

Endpoint

POST /api/admin/organizations/:id/members

Request Body

Field	Type	Required	Description
`user_id`	string	✓	User ID
`role`	string	-	Organization role (`admin`, `member`, default: `member`)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/organizations/org_abc123/members" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_new789",
    "role": "member"
  }'

Response Example

{
  "organization_id": "org_abc123",
  "user_id": "usr_new789",
  "role": "member",
  "joined_at": 1706140800
}

Remove Member

Remove a member from an organization.

Endpoint

DELETE /api/admin/organizations/:id/members/:userId

Path Parameters

Parameter	Type	Required	Description
`id`	string	✓	Organization ID
`userId`	string	✓	User ID

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/organizations/org_abc123/members/usr_member002" \
  -H "Authorization: Bearer {token}"

Response

Status code 204 No Content (no body)

Get Hierarchy

Retrieve the organization hierarchy.

Endpoint

GET /api/admin/organizations/:id/hierarchy

Query Parameters

Parameter	Type	Required	Description
`depth`	integer	-	Depth of hierarchy to retrieve (default: unlimited)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/organizations/org_abc123/hierarchy?depth=3" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "id": "org_abc123",
  "name": "Engineering",
  "display_name": "Engineering Department",
  "member_count": 25,
  "children": [
    {
      "id": "org_def456",
      "name": "Backend",
      "display_name": "Backend Team",
      "member_count": 10,
      "children": [
        {
          "id": "org_sub001",
          "name": "API",
          "display_name": "API Team",
          "member_count": 5,
          "children": []
        }
      ]
    },
    {
      "id": "org_ghi789",
      "name": "Frontend",
      "display_name": "Frontend Team",
      "member_count": 8,
      "children": []
    }
  ]
}