Skip to main content

Role Membership and Mapping APIs

The Role Membership and Mapping APIs provide endpoints to view, assign, and remove role memberships in IQ Server. These APIs let administrators manage which users and groups belong to specific roles across global and non-global scopes. They extend access control functionality by enabling programmatic management of role-to-member relationships.

Permissions Required

Scope

Operation

Required Permission

Non-global

View memberships

View IQ Elements

Non-global

Assign/unassign members

Edit Access Control

Global

All operations

Edit System Configuration and Users

Set Members for a Role (Non-Global)

Replaces the entire list of members for a given role within a specific context.

PUT /api/v2/roleMemberships/{ownerType}/{ownerId}/role/{roleId}/members

Example:

curl -u admin:admin123 -X PUT \
  -H "Content-Type: application/json" \
  -d '[{"type":"USER","internalName":"user1","displayName":"User One","email":"[email protected]","realm":"IQ Server"}]' \
  http://localhost:8070/api/v2/roleMemberships/application/myApp/role/abcd123/members

  • ownerType: application, organization, repository, or repository_manager

  • ownerId: Application public ID or internal organization/repository ID

Note

This operation replaces the existing member list for the role. Any members not included in the request will be removed.

Set Members for a Role (Global)

PUT /api/v2/roleMemberships/{ownerType}/role/{roleId}/members

Example:

curl -u admin:admin123 -X PUT \
  -H "Content-Type: application/json" \
  -d '[{"type":"USER","internalName":"admin","displayName":"Administrator","realm":"IQ Server"}]' \
  http://localhost:8070/api/v2/roleMemberships/global/role/{roleId}/members

  • ownerType: global or repository_container

Note

Returns 400 Bad Request if assigning application-level roles at the global level.

Get All Roles with Members (Non-Global)

Retrieves all roles and their associated members for a specific context.

GET /api/v2/roleMemberships/{ownerType}/{ownerId}/roles

Example:

curl -u admin:admin123 -X GET \
  http://localhost:8070/api/v2/roleMemberships/application/myApp/roles

Get All Roles with Members (Global)

Retrieves all global roles and their associated members.

GET /api/v2/roleMemberships/{ownerType}/roles

Example:

curl -u admin:admin123 -X GET \
  http://localhost:8070/api/v2/roleMemberships/global/roles

Assign a Single User or Group to a Role

Assigns a single user or group to a role without replacing existing members.

Non-Global

PUT /api/v2/roleMemberships/{ownerType}/{ownerId}/role/{roleId}/{memberType}/{memberName}

Global

PUT /api/v2/roleMemberships/{ownerType}/role/{roleId}/{memberType}/{memberName}

Example:

curl -u admin:admin123 -X PUT \
  http://localhost:8070/api/v2/roleMemberships/application/myApp/role/1da70fae1fd54d6cb7999871ebdb9a36/user/developer1

  • memberType: user or group

  • memberName: Username or group name

Note

This is an additive operation. Existing members remain assigned.

Unassign a User or Group from a Role

Removes a single user or group from a specified role.

Non-Global

DELETE /api/v2/roleMemberships/{ownerType}/{ownerId}/role/{roleId}/{memberType}/{memberName}

Global

DELETE /api/v2/roleMemberships/{ownerType}/role/{roleId}/{memberType}/{memberName}

Example:

curl -u admin:admin123 -X DELETE \
  http://localhost:8070/api/v2/roleMemberships/global/role/1b92fae3e55a411793a091fb821c422d/user/testuser

Note

Returns 404 Not Found if the role or member cannot be found.

Get Simplified Role Memberships

Retrieves a compact view of all role memberships for a given scope.

Non-Global

GET /api/v2/roleMemberships/{ownerType}/{ownerId}

Global

GET /api/v2/roleMemberships/{ownerType}

Example:

curl -u admin:admin123 -X GET \
  http://localhost:8070/api/v2/roleMemberships/global

Note

Use this for summary information. For detailed role and membership data, use the Get All Roles with Members endpoints.

Request Body Example

When setting members for a role, include an array of member objects.

[
  {
    "type": "USER",
    "internalName": "user1",
    "displayName": "User One",
    "email": "[email protected]",
    "realm": "IQ Server"
  },
  {
    "type": "GROUP",
    "internalName": "dev-team",
    "displayName": "Development Team",
    "realm": "LDAP"
  }
]

Role Membership Behavior

The following rules apply when managing role memberships:

  • memberName must exactly match the internalName field from the GET response.

  • Each member must include both type and internalName.

  • The realm field is required for each member (for example, "IQ Server", "LDAP", or "SAML").

  • At least one user must always remain in the System Administrator role.

  • Global-level roles (e.g., System Administrator, Policy Administrator) can only be assigned globally.

  • Application-level roles cannot be assigned globally.

  • Role and member entries must exist before assignment.

  • Bulk operations (PUT /members) replace all members; single-member operations (PUT /user/{memberName}) are additive.

  • Role assignments are inherited down the organizational hierarchy (for example, organization → application).

Example Use Case

Assign a user to a role:

curl -u admin:admin123 -X PUT \
  http://localhost:8070/api/v2/roleMemberships/application/myApp/role/1da70fae1fd54d6cb7999871ebdb9a36/user/developer1

Remove that user from the role:

curl -u admin:admin123 -X DELETE \
  http://localhost:8070/api/v2/roleMemberships/application/myApp/role/1da70fae1fd54d6cb7999871ebdb9a36/user/developer1