# 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":"user1@example.com","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": "user1@example.com",\
    "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
```