feat(users)!: backend for managing user roles in admin panel

[Samk13]

❤️ Thank you for your contribution!

Description

• Add backend support in admin panel APIs for managing user roles.
• Add bulk role update/delete via /users/<id>/groups.
• Support role lookup by name or id in bulk mutations.
• Return 403 for unknown roles.
• Update user role management tests.

depends on: inveniosoftware/invenio-app-rdm#3354

Note: This PR was initially generated with AI assistance and then refactored and cleaned up. The implementation has been reviewed, but additional feedback is more than welcome.

Breaking change

Users' index behavior changed; reindex is required:

invenio index destroy --yes-i-know
invenio index init
invenio rdm rebuild-all-indices

Screen.Recording.2026-03-05.at.13.33.44.mov

User Roles API (Bulk + Incremental)

This PR introduces an API model for managing user roles with both bulk and incremental operations:

• Bulk replace (PUT) is used by the UI for performance and consistency:

  • one request applies the full desired role state

  • avoids multiple round-trip when updating many roles

  • supports deterministic add/remove in a single call

    Note: this endpoint will replace all existing roles with the provided list in the json body.
    it is intended for UI use for efficient updates.

• Incremental add (POST) and incremental remove (DELETE) are intended for API consumers that want non-destructive, stepwise updates.

1. List user roles

• Method: GET
• URL: /api/users/<user_id>/groups
• Body: none

Example:

GET /api/users/<user_id>/groups

response:

HTTP/1.1 200 OK
{
    "groups": [
        {
            "id": "<uuid>",
            "name": "<role_name>"
        },
        {
            "id": "<uuid>",
            "name": "<role_name>"
        }
    ],
    "total": 2
}

2. Bulk replace roles (UI-oriented)

• Method: PUT
• URL: /api/users/<user_id>/groups
• Semantics: final roles become exactly the provided list (adds missing, removes extra)

Example:

PUT /api/users/<user_id>/groups
Content-Type: application/json

{
  "groups": ["it-dep", "hr-dep"]
}

response:
HTTP/1.1 200 OK
{
    "added": [],
    "groups": [
        "408f37a0-183b-46b1-857f-7e83a108eb76",
        "a0eb5358-4a02-4b08-aa86-f5e0eabee753",
    ],
    "removed": ["<previously-assigned-role-id>"]
}

---

3. Add roles without removing existing ones (API-oriented)

• Method: POST
• URL: /api/users/<user_id>/groups
• Semantics: adds only roles not already assigned; keeps existing roles untouched

Example:

POST /api/users/<user_id>/groups
Content-Type: application/json

{
  "groups": [<role_id>, <or_role_name>]
}

---

4. Remove specific roles (API-oriented)

• Method: DELETE
• URL: /api/users/<user_id>/groups
• Semantics: removes only the listed roles

Example:

DELETE /api/users/<user_id>/groups
Content-Type: application/json

{
  "groups": ["<role_id>", "<or_role_name>"]
}

---

Payload Notes

• Expected payload key: groups (list of role IDs/names as strings).
• role_ids is also accepted for backward compatibility.
• Invalid/unknown roles are denied according to existing permission and validation rules.

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

• I'm aware of the code of conduct.
• I've created logical separate commits and followed the commit message format.
• I've added relevant test cases.
• I've added relevant documentation.
• I've marked translation strings.
• I've identified the copyright holder(s) and updated copyright headers for touched files (>15 lines contributions).
• I've NOT included third-party code (copy/pasted source code or new dependencies).
  • If you have added third-party code (copy/pasted or new dependencies), please reach out to an architect on Discord.

Frontend

• I've followed the CSS/JS and React guidelines.
• I've followed the web accessibility guidelines.
• I've followed the user interface guidelines.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

1. You license your contribution under the same terms as the current repository’s license.
2. You agree that you have the right to license your contribution under the current repository’s license.