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

Minimal Example

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

{
  "clientId": "web-app",
  "resources": [
    {
      "name": "documents",
      "scopes": ["read"]
    }
  ],
  "context": {}
}

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 the user's membership from the organization. The planned KEOPS lifecycle cascade also revokes durable role assignments anchored to that exact membership, including direct and organization-template-sourced rows whose source assignment identifiers differ.

Delivery status

The exact-membership role cleanup guarantee is tracked by KEOPS #320. Until that change and its role-management dependency are released and deployed, this endpoint description must not be interpreted as proof that stale role rows or already-issued access tokens are immediately invalidated.

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 exact organization-membership anchors
Creating a membership is additive; it does not implicitly remove another active membership
The planned disable/remove cascade affects only roles anchored to the transitioned membership
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

Durable membership-role cleanup, organization-context switching, and issued-token invalidation are separate controls. Removing membership A must preserve roles anchored to membership B, and cleanup does not rewrite an already-issued self-contained access token. See Org-Aware Tokens & Sessions.

Next Step

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

Organization API

Organization and department management

Token Claims Reference

JWT claims used in authorization

Authorization Models

RBAC, ABAC, ReBAC concepts

Scope​

Definitions​

Allowed Values​

Used By​

Minimal Example​

Diagram​

Role Management​

List Global Roles​

List Organization Roles​

List Available Roles​

Create Role​

Add Role to Organization​

Remove Role from Organization​

Role Assignments​

Assign User to Organization​

List Users in Organization​

Get User Assignments​

Get User Assignments Tree​

Remove User from Organization​

Authorization​

Evaluate Permissions​

Get Organization Context​

Status Codes​

Invalid Example​

Notes​

Next Step​

Related Docs​

Organization API

Token Claims Reference

Authorization Models

Scope

Definitions

Allowed Values

Used By

Minimal Example

Diagram

Role Management

List Global Roles

List Organization Roles

List Available Roles

Create Role

Add Role to Organization

Remove Role from Organization

Role Assignments

Assign User to Organization

List Users in Organization

Get User Assignments

Get User Assignments Tree

Remove User from Organization

Authorization

Evaluate Permissions

Get Organization Context

Status Codes

Invalid Example

Notes

Next Step

Related Docs