REST API

REST API

Everything the role manager UI does goes through a REST API, so roles, user assignments, and permission lookups can all be scripted. The base path is:

/api/extensions/rbac

Interactive Documentation

Full endpoint documentation, including request/response schemas and the ability to try calls live, is available through OIE's built-in Swagger UI. Look for the Role-Based Access Control tag.

Authentication

All requests require OIE credentials. Use HTTP Basic Authentication or session-based authentication, consistent with other OIE API calls, and send the X-Requested-With header the engine's API expects. Requests and responses are available as JSON or XML.

Permissions

The plugin declares two extension permissions of its own:

Permission	Grants
View Roles	Read access: list and fetch roles, look up user assignments, browse the permission catalog
Manage Roles	Write access: create, update, and delete roles; assign and remove user roles

Two discovery endpoints, /my-permissions and /task-permissions, are whitelisted for every authenticated user because the client UI needs them before it knows what the user holds. Users assigned to the admin role bypass permission checks entirely.

Roles

Method	Path	Purpose	Permission
GET	/roles	List all roles with their permission and channel sets	View Roles
GET	/roles/{roleId}	Fetch one role	View Roles
POST	/roles	Create a role	Manage Roles
PUT	/roles/{roleId}	Update a role's name, description, permissions, and channel restrictions	Manage Roles
DELETE	/roles/{roleId}	Delete a role	Manage Roles

• Create assigns the id from the database and always produces a non-admin role. Role names must be unique.
• Update never changes the admin flag. Updates to the admin role must keep its full core permission set and cannot add channel restrictions.
• Delete refuses to delete the admin role.

User Assignment

Each user holds at most one role. Assigning a new role replaces the old one.

Method	Path	Purpose	Permission
GET	/users/{userId}/role	Return the role assigned to a user, or an empty 204 response if unassigned	View Roles
POST	/users/{userId}/role/{roleId}	Assign a role to a user, replacing any prior assignment	Manage Roles
DELETE	/users/{userId}/role	Remove the user's role assignment; the user then holds no role and is denied every gated operation	Manage Roles

Assignment and removal are checked against the admin floor: a request that would leave zero users on the admin role is refused.

Permission Discovery

Method	Path	Purpose	Permission
GET	/permissions	The full permission catalog: every core engine permission plus every registered extension permission	View Roles
GET	/my-permissions	The calling user's effective permissions. Admins get everything; a user with no role gets an empty set	Whitelisted
GET	/task-permissions	Task-name to permission mappings declared by installed extensions	Whitelisted
GET	/permissions/extensions	Maps each extension permission to the plugin that publishes it, e.g. "View Thread Dump" to "Thread Viewer"	View Roles

GET /permissions/extensions was added in v1.1.2. Older servers return 404 for this path.

Example: List Roles

curl -u admin:yourpassword \
  -H "X-Requested-With: OpenIntegrationEngine" \
  https://localhost:8443/api/extensions/rbac/roles

Add -k if the server uses a self-signed certificate. Set Accept: application/json or Accept: application/xml to pick the response format.

Example: Create a Role

POST an XStream-serialized Role to /roles with Content-Type: application/xml:

<com.diridium.rbac.Role>
  <name>Interface Operators</name>
  <description>Dashboard and message access for the interface team</description>
  <permissions>
    <string>viewDashboard</string>
    <string>viewChannels</string>
    <string>viewMessages</string>
  </permissions>
  <channelIds>
    <string>2fbb1cc5-3a44-4d21-b6c2-7e0a4f9d8e11</string>
  </channelIds>
  <isAdmin>false</isAdmin>
</com.diridium.rbac.Role>

• Omit <id>. The database assigns it, and the response body is the persisted role with its new id.
• <permissions> holds one <string> per grant: core permission identifiers or extension permission display names. GET /permissions returns the valid values.
• <channelIds> is a channel whitelist, one channel id per <string>. Leave it empty for unrestricted access.
• <isAdmin> is ignored on create. Roles created through the API are always non-admin.

Errors

• Missing permission - calling an endpoint without the required permission returns 403 Forbidden with the missing permission named in the reason phrase, for example Missing permission: Manage Roles.
• Admin guard violations - a write that would weaken the admin role or leave the server without an admin returns 400 Bad Request with a plain-text message, for example Cannot delete the admin role or Cannot remove the role assignment from the last admin user; assign another admin first.