Role & Authorization API Reference

Scope

The Role & Authorization API provides endpoints for role management, role assignments, and runtime authorization decisions. It covers role lifecycle operations and permission evaluation at request time.

Definitions

Term	Description
Global Role	A realm-level role available across all organizations
Organization Role	A role scoped to a specific organization
Role Assignment	The association between a user and a role through organization membership
Authorization Decision	The result of evaluating permissions for a resource-scope combination

Allowed Values

Field	Allowed Values	Description
status (authorization)	GRANT, DENY, ERROR	Authorization decision result
isGlobal	true, false	Filter for global roles
includeGlobal	true, false	Include global roles in results

Used By

• Policy Development
• Organization Model
• Access Gateway

---

Diagram

---

Role Management

Base path: /admin/realms/{realm}/organizations

List Global Roles

GET /global/roles

Lists all realm-level roles.

Query Parameters:

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

Response:

{
  "metaData": {
    "currentPagination": {
      "offset": 0,
      "count": 50
    },
    "totalRows": 25
  },
  "results": [
    {
      "id": "role_001",
      "name": "admin",
      "description": "Administrator role",
      "attributes": {}
    }
  ]
}

List Organization Roles

GET /{orgId}/roles

Lists roles assigned to a specific organization.

Query Parameters:

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

Response:

{
  "metaData": {
    "currentPagination": {
      "offset": 0,
      "count": 50
    },
    "totalRows": 10
  },
  "results": [
    {
      "id": "role_002",
      "name": "department-manager",
      "description": "Department manager role",
      "attributes": {
        "level": ["manager"]
      }
    }
  ]
}

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

Create Role

POST /{orgId}/roles/create

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

Request Body:

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

Response:

{
  "result": {
    "id": "role_002",
    "name": "department-manager",
    "description": "Department manager role"
  }
}

Add Role to Organization

POST /{orgId}/roles

Assigns an existing role to the organization.

Request Body:

{
  "roleId": "role_001"
}

Remove Role from Organization

DELETE /{orgId}/roles/{roleId}

Removes a role from the organization.

---

Role Assignments

Assign User to Organization

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

Assigns a user to an organization department, granting associated roles.

Request Body:

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

Response:

{
  "result": {
    "userId": "user_001",
    "departmentId": "dept_001",
    "assignedAt": "2024-01-15T10:30:00Z"
  }
}

List Users in Organization

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"
    }
  ],
  "totalRows": 15
}

Get User Assignments

GET /users/{userId}/assignments

Lists all organization and role assignments for a user.

Response:

{
  "results": [
    {
      "userId": "user_001",
      "organizationId": "org_001",
      "organizationName": "Engineering",
      "departmentId": "dept_001",
      "departmentName": "Backend Team"
    }
  ]
}

Get User Assignments Tree

GET /users/{userId}/assignments-tree

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

Response:

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

Remove User from Organization

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

Removes user from organization, revoking associated role assignments.

---

Authorization

Base path: /realms/{realm}/authorization-decision-provider

Evaluate Permissions

POST /realms/{realm}/authorization-decision-provider/authorize

Evaluates authorization for resources with specified scopes.

Request Headers:

Header	Required	Description
Authorization	Yes	Bearer token (JWT)
Content-Type	Yes	application/json

Request Body:

{
  "clientId": "web-app",
  "resources": [
    {
      "name": "documents",
      "scopes": ["read", "write"]
    },
    {
      "name": "settings",
      "scopes": ["admin"]
    }
  ],
  "context": {
    "attributes": {
      "method": "POST",
      "path": "/api/documents",
      "headers": "{}",
      "body": "{}"
    }
  }
}

Response:

{
  "status": "GRANT",
  "permissions": [
    {
      "resource": "documents",
      "scope": "read",
      "status": "GRANT"
    },
    {
      "resource": "documents",
      "scope": "write",
      "status": "GRANT"
    },
    {
      "resource": "settings",
      "scope": "admin",
      "status": "DENY"
    }
  ]
}

Status Values:

Status	Description
GRANT	Permission granted
DENY	Permission denied
ERROR	Evaluation error

Get Organization Context

POST /realms/{realm}/authorization-decision-provider/get-organizations

Retrieves organization context for the authenticated user.

Request Body:

{
  "clientId": "web-app"
}

Response:

{
  "status": true,
  "organization": {
    "userId": "user_001",
    "tenants": [
      {
        "tenantId": "tenant_001",
        "tenantName": "Acme Corp"
      }
    ]
  }
}

---

Status Codes

Code	Description
200	Success
201	Resource created
400	Bad request — validation error
401	Unauthorized — invalid or missing token
403	Forbidden — insufficient permissions
404	Resource not found
500	Server error

Invalid Example

The following request fails because resources is empty:

{
  "clientId": "web-app",
  "resources": [],
  "context": {}
}

Error Response:

{
  "error": "Bad Request",
  "message": "resources array cannot be empty"
}

Notes

• Manage role assignments through organization memberships
• Authorization evaluation supports batch requests with multiple resources
• Each resource-scope combination returns an individual status
• Global roles are available across all organizations in the realm

warning

Removing a user from an organization revokes all role assignments associated with that organization membership.

Next Step

After configuring roles and assignments, implement authorization checks in your application using the Access Gateway for request-level enforcement.

Related Docs

Organization API

Organization and department management

Token Claims Reference

JWT claims used in authorization

Authorization Models

RBAC, ABAC, ReBAC concepts