## Why Companion to #602144, which delivered the **write** side of the GraphQL wrapper over the IAM Relationships API (grant/bulk-grant). Clients also need to **read back** existing role assignments for Artifact Registry (AR) resources (org/namespace and repository scope) without proxying through the AR binaries, for the same reasons as the write path: the Relationships API is gRPC-only, authenticated with a short-lived JWT, and Rails is the place that mints it. The IAM-service side of lookup is implemented in `gitlab-org/auth/iam`: base `LookupRelationships` support plus keyset pagination in [!403](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/403) (`lookup.v1.LookupService#LookupRelationships`). ## What A GraphQL query in Rails that: - Wraps the gRPC `LookupRelationships` RPC exposed by the IAM Relationships API's lookup service. - Accepts a normal user credential (e.g. PAT) and internally exchanges it for a short-lived JWT attached as `Bearer` metadata, following the exact pattern already delivered for writes: `Authn::TokenExchange::TokenIssuer` → `Authn::IamService::*Client` (see [`lib/authn/iam_service/relationships_client.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/authn/iam_service/relationships_client.rb) and [`ee/app/services/authz/artifact_registry/grant_role_assignments_service.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/services/authz/artifact_registry/grant_role_assignments_service.rb)). - Targets AR resource scopes (namespace and/or repository, each optionally qualified by ancestors) and supports filtering by relationship kind and role. - Surfaces the RPC's keyset pagination (`page_size` / `page_token` / `next_page_token`) through GraphQL, ideally as a Relay-style connection, rather than reimplementing cursoring in Rails. Illustrative contract (from `gitlab-org/auth/iam`, `proto/lookup`): ``` LookupRelationshipsRequest { objects: []Object // each with optional ancestors filter: LookupFilter { kinds: []Kind, roles: []Role } page_size: int32 page_token: string } LookupRelationshipsResponse { relationships: []Relationship next_page_token: string } ``` ## Decision (2026-07-27): this endpoint returns role assignments This endpoint is the read for Artifact Registry role assignments, the memberships, and the counterpart to the grant and bulk-grant writes. Its purpose is to show who holds which role on a resource, for end-users now and the UI later. The relationships store is a general zanzibar-style tuple table and will hold other kinds (parent, seal, visibility) as they land. This endpoint returns role assignments only, so those structural and visibility tuples never surface through it. The read is scoped to `KIND_ASSIGNMENT` internally and there is no caller-facing kind filter. The role filter stays. A general relationship read, if it is ever needed, is a separate API, not a widening of this one. This supersedes the "filtering by relationship kind" language in **What** and the `kind` half of the "unrecognized `kind` or `role` filter value" criterion. ## How Mirror the write-path layering: ``` GraphQL query (e.g. artifactRegistryRoleAssignments) │ user PAT / session ▼ Service (validate caller/org, build LookupRelationshipsRequest, mint JWT) ▼ Authn::IamService client wrapper (< BaseClient), modeled on RelationshipsClient │ metadata: { 'authorization' => "Bearer <jwt>" } ▼ IAM Lookup API (gRPC, lookup.v1.LookupService#LookupRelationships) ``` Depends on the IAM-service pagination work in [!403](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/403). ## Out of scope - Grant / bulk grant (write path) — delivered in #602144. - Delete / revoke — tracked in a separate issue. - The user management UI, role <> permission mapping, and the Relationships API service itself (tracked under [&21743](https://gitlab.com/groups/gitlab-org/-/work_items/21743)). ## Acceptance criteria: error handling - [ ] An unauthenticated caller, or a caller with the relevant feature flag disabled, receives a top-level "resource not available" GraphQL error, and the lookup service is never invoked. - [ ] A resource/object outside the caller's own organization returns a generic not-found/authorization error rather than leaking whether it exists. - [ ] A non-UUID resource/object id returns a validation error. - [ ] An unrecognized `kind` or `role` filter value returns a validation error. - [ ] A `page_token` minted for a different query (different org, objects, or filter) is rejected with a clear error rather than silently repositioning an unrelated scan (mirrors the fingerprint check in IAM's `cursor.go`). - [ ] A malformed/tampered `page_token` returns a clear GraphQL error, not an unhandled exception. - [ ] gRPC/backend failures (`GRPC::BadStatus`, IAM data-access configuration errors) are caught, reported via `Gitlab::ErrorTracking`, and surfaced as a GraphQL error rather than a 500 or raw exception. - [ ] An empty result set returns an empty (but valid) connection, not an error. - [ ] Requested page sizes are clamped to the backend's documented bounds (IAM's max is 999) rather than erroring or being forwarded unbounded.