Backend: Define API contract for user-grouped data

[BryanttV]

Description

Design and document the contract (possibly with an ADR) for the endpoint that will return roles and permissions grouped by user (instead of a flat list).

Changes must support efficient filtering by organization, roles, and scopes, as well as searches by full name, username, or email address.

Figma Design

Possible Development Plan

• Use canonical endpoint: GET /api/authz/v1/users/ (do not change the /assignments/ response shape).
• Filter semantics: a user is included if they have ≥1 matching assignment; the nested list shows only matching assignments; assignation_count is the filtered count.
• Preview: assignments_limit default 3.
• “View all roles” → GET /users/<username>/assignments/ with the same orgs/roles/scopes.
• New fields: assignments[], scope_display_name, scope_type.
• Table sort: user fields only (username, email, full_name).

This is just one possible solution; another decision can be made.

Checklist

• Define the response JSON shape (user → roles → nested permissions)
• Document the modifications or creation of new endpoints, possibly in an ADR.
• Review with the backend team before implementation.