Organization API Reference

Scope

The Organization API provides REST endpoints for managing organizational hierarchy, departments, user assignments, roles, groups, and applications within a Tenant. Organizations enable multi-level hierarchical structures for enterprise identity and access management.

Definitions

Term	Description
Organization	A root-level container within a Tenant for grouping departments and users
Department	A sub-unit within an Organization that can contain users and nested sub-departments
Sub-Department	A nested department within a parent department
Alias	A unique human-readable identifier for an organization or department
Assignment	The association between a user and a department

Allowed Values

Field	Allowed Values	Description
`sortOrder`	`ASC`, `DESC`	Sort direction for list queries
`isGlobal`	`true`, `false`	Filter for global roles
`includeGlobal`	`true`, `false`	Include global roles in results

Used By

Diagram

Organizations support multi-level hierarchical structures: Tenant → Organization → Department → Sub-Department.

Base Path

/admin/realms/{realm}/organizations

All endpoints require realm management permissions.

Organizations

Create Organization

POST /

Creates a new root-level organization within the tenant.

Request Body:

{
  "name": "Engineering Division",
  "alias": "engineering",
  "description": "Engineering department",
  "attributes": {
    "costCenter": ["ENG-400"]
  }
}

Response:

{
  "result": {
    "id": "org_001",
    "name": "Engineering Division",
    "alias": "engineering",
    "description": "Engineering department",
    "attributes": {
      "costCenter": ["ENG-400"]
    }
  }
}

Status Codes: 201 Created, 400 Bad Request, 409 Conflict (alias exists)

Search by Alias

GET /alias/{alias}

Retrieves an organization by its unique alias.

Response: Organization details

Status Codes: 200 OK, 404 Not Found

Get Organization

GET /{orgId}

Retrieves organization details by ID.

Response:

{
  "result": {
    "id": "org_001",
    "name": "Engineering Division",
    "alias": "engineering",
    "description": "Engineering department",
    "attributes": {
      "costCenter": ["ENG-400"]
    }
  }
}

Update Organization

PUT /{orgId}

Updates organization metadata.

Request Body:

{
  "name": "Engineering Division",
  "description": "Updated description",
  "attributes": {
    "costCenter": ["ENG-500"]
  }
}

Status Codes: 200 OK, 400 Bad Request, 403 Forbidden

Delete Organization

DELETE /{orgId}

Deletes an organization.

Status Codes: 200 OK, 403 Forbidden

Departments

Departments are sub-organizations within a parent organization, supporting nested hierarchies.

List Departments

GET /{orgId}/departments

Query Parameters:

Parameter	Type	Default	Description
`offset`	integer	0	Pagination offset
`count`	integer	20	Results per page

Response:

{
  "metaData": {
    "currentPagination": {
      "offset": 0,
      "count": 20
    },
    "totalRows": 45
  },
  "results": [
    {
      "id": "dept_001",
      "name": "Backend Team",
      "alias": "backend",
      "parentId": "org_001"
    }
  ]
}

Get Organization Tree

GET /{orgId}/departments/tenant-tree

Returns hierarchical tree view of organization structure.

Response:

{
  "result": [
    {
      "id": "org_001",
      "name": "Engineering",
      "children": [
        {
          "id": "dept_001",
          "name": "Backend Team",
          "children": []
        }
      ]
    }
  ]
}

Create Department

POST /{orgId}/departments

Request Body:

{
  "name": "Frontend Team",
  "description": "Frontend development team",
  "alias": "frontend",
  "attributes": {
    "location": ["Building A"]
  }
}

Status Codes: 201 Created, 400 Bad Request

Get Department

GET /{orgId}/departments/{departmentId}

Retrieves department details by ID.

Response:

{
  "result": {
    "id": "dept_001",
    "name": "Backend Team",
    "alias": "backend",
    "description": "Backend development team",
    "parentId": "org_001",
    "attributes": {
      "location": ["Building A"]
    }
  }
}

Status Codes: 200 OK, 404 Not Found

Update Department

PUT /{orgId}/departments/{departmentId}

Updates department metadata.

Request Body:

{
  "name": "Backend Engineering",
  "description": "Updated description",
  "attributes": {
    "location": ["Building B"]
  }
}

Status Codes: 200 OK, 400 Bad Request, 403 Forbidden

Delete Department

DELETE /{orgId}/departments/{departmentId}

Deletes a department and all its sub-departments.

Status Codes: 200 OK, 403 Forbidden, 404 Not Found

Sub-Departments

Sub-departments enable deeper nesting within departments.

Method	Endpoint	Description
`GET`	`/{orgId}/departments/{departmentId}/sub-departments`	List sub-departments
`POST`	`/{orgId}/departments/{departmentId}/sub-departments`	Create sub-department
`GET`	`/{orgId}/departments/{departmentId}/sub-departments/{subDeptId}`	Get sub-department
`PUT`	`/{orgId}/departments/{departmentId}/sub-departments/{subDeptId}`	Update sub-department
`DELETE`	`/{orgId}/departments/{departmentId}/sub-departments/{subDeptId}`	Delete sub-department

Sub-department request and response structures follow the same format as departments.

User Assignments

List Users in Department

GET /{orgId}/departments/{departmentId}/users

Query Parameters:

Parameter	Type	Default	Description
`offset`	integer	0	Pagination offset
`count`	integer	20	Results per page

Response:

{
  "results": [
    {
      "userId": "user_001",
      "username": "jane.doe",
      "departmentId": "dept_001",
      "assignedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Assign User to Department

POST /{orgId}/departments/{departmentId}/users

Request Body:

{
  "userId": "user_001",
  "departmentId": "dept_001"
}

Status Codes: 200 OK, 400 Bad Request

Remove User from Department

DELETE /{orgId}/departments/{departmentId}/users/{userId}

Get User Assignments

GET /users/{userId}/assignments

Lists all organization assignments for a specific user.

Get User Assignments Tree

GET /users/{userId}/assignments-tree

Returns hierarchical tree view of organizations the user is assigned to.

Roles

List Organization Roles

GET /{orgId}/roles

Query Parameters:

Parameter	Type	Default	Description
`offset`	integer	0	Pagination offset
`count`	integer	50	Results per page
`isGlobal`	boolean	false	Include global roles

List Available Roles

GET /{orgId}/roles/available

Lists roles not yet assigned to the organization.

Query Parameters:

Parameter	Type	Default	Description
`offset`	integer	0	Pagination offset
`count`	integer	50	Results per page
`includeGlobal`	boolean	false	Include global roles

Add Role to Organization

POST /{orgId}/roles

Request Body:

{
  "roleId": "role_001"
}

Create and Add Role

POST /{orgId}/roles/create

Creates a new realm role and assigns it to the organization.

Request Body:

{
  "name": "department-admin",
  "description": "Department administrator role",
  "attributes": {
    "level": ["admin"]
  }
}

Remove Role from Organization

DELETE /{orgId}/roles/{roleId}

List Global Roles

GET /global/roles

Query Parameters:

Parameter	Type	Default	Description
`offset`	integer	0	Pagination offset
`count`	integer	50	Results per page
`search`	string	—	Search filter

Groups

List Organization Groups

GET /{orgId}/groups

Add Group to Organization

POST /{orgId}/groups

Request Body:

{
  "groupId": "group_001"
}

Remove Group from Organization

DELETE /{orgId}/groups/{groupId}

Applications

List Organization Applications

GET /{orgId}/applications

Query Parameters:

Parameter	Type	Default	Description
`offset`	integer	0	Pagination offset
`count`	integer	20	Results per page
`search`	string	—	Search filter
`sortBy`	string	name	Sort field
`sortOrder`	string	ASC	ASC or DESC
`tag`	string	—	Filter by tag

Assign Application

POST /{orgId}/applications/assign

Assigns an existing catalog application to the organization.

Get Application Details

GET /{orgId}/applications/{clientId}

Unassign Application

DELETE /{orgId}/applications/{clientId}

Removes application from organization without deleting it.

Global Application Catalog

GET    /global/applications
POST   /global/applications
GET    /global/applications/{appId}
PUT    /global/applications/{appId}
DELETE /global/applications/{appId}

Property Templates

Custom attribute templates for organizations.

GET    /{orgId}/property-templates
POST   /{orgId}/property-templates
GET    /{orgId}/property-templates/{templateId}
PUT    /{orgId}/property-templates/{templateId}
DELETE /{orgId}/property-templates/{templateId}

Department Templates

Reusable templates for consistent department structure.

GET    /{orgId}/department-templates
POST   /{orgId}/department-templates
GET    /{orgId}/department-templates/{templateId}

Pagination

All list endpoints support pagination with consistent response structure:

{
  "metaData": {
    "currentPagination": {
      "offset": 0,
      "count": 20,
      "sortBy": "name",
      "sortOrder": "ASC"
    },
    "totalRows": 150
  },
  "results": []
}

Status Codes

Code	Description
`200`	Success
`201`	Resource created
`400`	Bad request — validation error
`403`	Forbidden — insufficient permissions
`404`	Resource not found
`409`	Conflict — resource already exists
`500`	Server error

Invalid Example

Creating an organization with a duplicate alias returns 409 Conflict:

{
  "name": "Another Engineering",
  "alias": "engineering"
}

Response:

{
  "error": "Conflict",
  "message": "Organization alias 'engineering' already exists"
}

Notes

All endpoints require realm management permissions
Organization aliases must be unique within a realm
Deleting an organization removes all associated departments and assignments
User assignments are independent of role assignments

warning

Deleting a parent organization cascades to all child departments. Verify the hierarchy before deletion.

Next Step

After setting up organizations and departments, configure role assignments and authorization policies using the Role & Authorization API.

Tenant API

Tenant management endpoints

Role & Authorization API

Role and permission management

Organization Model

Organization concepts and hierarchy

Scope​

Definitions​

Allowed Values​

Used By​

Diagram​

Base Path​

Organizations​

Create Organization​

Search by Alias​

Get Organization​

Update Organization​

Delete Organization​

Departments​

List Departments​

Get Organization Tree​

Create Department​

Get Department​

Update Department​

Delete Department​

Sub-Departments​

User Assignments​

List Users in Department​

Assign User to Department​

Remove User from Department​

Get User Assignments​

Get User Assignments Tree​

Roles​

List Organization Roles​

List Available Roles​

Add Role to Organization​

Create and Add Role​

Remove Role from Organization​

List Global Roles​

Groups​

List Organization Groups​

Add Group to Organization​

Remove Group from Organization​

Applications​

List Organization Applications​

Assign Application​

Get Application Details​

Unassign Application​

Global Application Catalog​

Property Templates​

Department Templates​

Pagination​

Status Codes​

Invalid Example​

Notes​

Next Step​

Related Docs​

Tenant API

Role & Authorization API

Organization Model

Scope

Definitions

Allowed Values

Used By

Diagram

Base Path

Organizations

Create Organization

Search by Alias

Get Organization

Update Organization

Delete Organization

Departments

List Departments

Get Organization Tree

Create Department

Get Department

Update Department

Delete Department

Sub-Departments

User Assignments

List Users in Department

Assign User to Department

Remove User from Department

Get User Assignments

Get User Assignments Tree

Roles

List Organization Roles

List Available Roles

Add Role to Organization

Create and Add Role

Remove Role from Organization

List Global Roles

Groups

List Organization Groups

Add Group to Organization

Remove Group from Organization

Applications

List Organization Applications

Assign Application

Get Application Details

Unassign Application

Global Application Catalog

Property Templates

Department Templates

Pagination

Status Codes

Invalid Example

Notes

Next Step

Related Docs