Skip to content

User Groups and Permissions

User Groups let administrators manage access to Functional APIs and MCP tools at group level instead of per user. This page is for Hub administrators who create groups, assign users and grant API permissions.

Overview

A User Group is a collection of permissions and a security role that you assign to one or more Hub users. User Groups work with:

  • Basic authentication
  • OAuth authentication providers (such as Microsoft Entra ID / Azure AD)
  • MCP server tool filtering and authorization

With User Groups you can:

  • Organize users into logical groups.
  • Grant access to specific Program Calls.
  • Grant access to specific RPA definitions.
  • Assign the User or Admin role.
  • Control which APIs appear in discovery endpoints.
  • Control which MCP tools are available to AI agents.

Concepts

User

A Hub user is authenticated through Basic authentication. A user can belong to multiple User Groups.

User Group

A User Group is a logical collection of permissions and a security role. Each group has:

  • Group name
  • Role (Admin or not)
  • Program Call permissions
  • Data API permissions
  • RPA permissions
  • Assigned users

Permission levels

Two permission levels are supported.

Regular functional access (not Admin)

Members can:

  • Execute permitted Functional APIs.
  • View permitted definitions.
  • Use permitted MCP tools.

Members cannot access Admin APIs.

Built-in user group

The Hub creates a built-in non-admin group named user together with the default functional user. Members of the user group (and users with the user role provided by an OAuth provider) can execute all Program Calls, Data APIs and RPA Calls without any per-API permission.

Permissions assigned to a group apply to the groups that you create. A user who belongs only to such custom groups can execute only the APIs that these groups are permitted to use.

Admin

Administrative access. Members inherit administrative privileges. They can access Admin APIs, view and execute all Functional APIs (Program Calls, RPA Calls and Data APIs), and use all MCP tools.

Creating a User Group

Create a new group:

POST /admin/user-groups

Example request body:

{
  "groupName": "sales-users"
}

Setting the group role

After you create a group, assign its role.

To set the group as User, which is the recommended role for application users:

GET /admin/user-groups/{groupName}/set/user

To set the group as Admin, which gives its members administrative privileges:

GET /admin/user-groups/{groupName}/set/admin

Creating users

Create a new Hub user:

POST /admin/users

Example request body:

{
    "username":"john",
    "rawPassword":"Password123"
}

Assigning users to groups

Add a user to a group:

POST /admin/users/{username}/groups/{groupName}

A user can belong to multiple groups.

To remove a user from a group:

DELETE /admin/users/{username}/groups/{groupName}

Managing Program Call and Data API permissions

Grant access to a Program Call or Data API definition:

POST /admin/user-groups/{groupName}/permissions/{programCallDefinition}

Remove the permission:

DELETE /admin/user-groups/{groupName}/permissions/{programCallDefinition}

Users who belong to a custom group can execute the corresponding Program Call API or Data API only if one of their groups has this permission. Administrators and members of the built-in user group can execute all APIs.

Managing RPA permissions

Grant access to an RPA definition:

POST /rpa/admin/{groupName}/permissions/{rpaDefinition}

Remove the permission:

DELETE /admin/user-groups/{groupName}/permissions/{rpaDefinition}

Only authorized users can execute the corresponding Screen Automation endpoint.

Viewing group information

Retrieve group information:

GET /admin/user-groups/{groupName}

Retrieve the assigned permissions:

GET /admin/user-groups/{groupName}/permissions

List all groups:

GET /admin/user-groups

Viewing user information

Retrieve user information:

GET /admin/users/{username}

List all users:

GET /admin/users

Allowed definitions

The Hub provides an endpoint that returns only the definitions available to the authenticated user:

GET /api/me/allowed-definitions

Depending on the assigned User Groups, the response can contain:

  • Program Calls
  • Data APIs
  • RPA definitions

Example response:

[
    {
        "name":"POSTORDSPQUERY",
        "type":"program-call"
    },
    {
        "name":"orderStatusURI",
        "type":"rpa"
    }
]

Administrators receive all registered definitions.

Permission enforcement

User Groups are enforced automatically during Functional API execution. If a user executes an API without the required permission, the Hub rejects the request. Administrators and members of the built-in user group are not restricted by API permissions.

Example response:

HTTP 403 Forbidden

Admin APIs remain inaccessible unless the user belongs to an Admin group.

MCP integration

When MCP is enabled, User Groups also apply to the dynamically generated MCP tools. During authentication, MCP retrieves the allowed definitions of the user from the Hub and provides only the permitted tools.

For example:

Permission Visible MCP tool
Program Call POSTORDSPQUERY_HUB
RPA orderStatusURI_RPA

Users cannot invoke tools that are not assigned to one of their groups. If a tool is unavailable, MCP returns an authorization error.

OAuth integration

User Groups can be mapped directly from OAuth provider roles. For Microsoft Entra ID (Azure AD), configure the Hub as follows:

auth.type=oauth

spring.oauth.resource.server.issuer-uri=https://...

spring.oauth.resource.server.authority.claim=roles

The value in the JWT roles claim must exactly match the name of the Hub User Group.

Example JWT payload:

{
    "roles": [
        "sales-users"
    ]
}

A user who receives this token inherits the permissions of the sales-users User Group. For the full provider setup, see OAuth Configuration Guide.

  1. Create a User Group.
  2. Set the group role.
  3. Create users.
  4. Assign users to the group.
  5. Grant Program Call permissions.
  6. Grant Data API permissions.
  7. Grant RPA permissions.
  8. Verify the accessible definitions:

    GET /api/me/allowed-definitions
    
  9. Execute the Functional APIs.

  10. Verify MCP tool visibility (if MCP is enabled).

Best practices

  • Manage permissions through User Groups instead of individual users.
  • Create separate groups for different business functions.
  • Grant only the minimum required permissions.
  • Reserve Admin groups for administrative users.
  • Use OAuth group mapping in production environments to avoid manual user administration.