Allow read_api scope on POST /api/v4/orbit/query

Dmitry Gruzdrequested to merge
fix/kg-514-orbit-query-read-api-scope into master

What does this MR do and why?

Fixes gitlab-org/orbit/knowledge-graph#514 (closed).

POST /api/v4/orbit/query is a read-only operation — it executes graph traversals against the Knowledge Graph service and does not mutate state. However, because API::Orbit::Data carries no allow_access_with_scope declarations, the global default (lib/api/api.rb lines 53–54) rejects read_api-scoped tokens on any non-GET/HEAD route, forcing integrators to mint api-scoped (read+write) tokens to run graph queries — a needless privilege escalation.

This MR adds allow_access_with_scope :read_api to ee/lib/api/orbit/data.rb, mirroring the precedent established by:

  • lib/api/glql.rb (GitLab Query Language) — same POST-for-read pattern
  • lib/api/markdown.rb (Markdown rendering) — same POST-for-read pattern

Both carry the comment # Although this API endpoint responds to POST requests, it is a read-only operation, which is reused here verbatim so the intent is discoverable.

Screenshots or screen recordings

N/A (API-only change).

How to set up and validate locally

  1. Ensure the knowledge_graph feature flag is on for your user.

  2. Mint a PAT with ONLY the read_api scope.

  3. Run:

    curl -sS -w "\nHTTP %{http_code}\n" \
  -H "PRIVATE-TOKEN: <read_api PAT>" \
  -H "Content-Type: application/json" \
  -d '{"query": {"nodes": ["MergeRequest"]}, "response_format": "llm"}' \
  https://<gdk-host>/api/v4/orbit/query

  4. Before this MR: 403 insufficient_scope. After: request proceeds to the Knowledge Graph service (response depends on namespace/FF configuration, but scope check passes).

Spec coverage added at ee/spec/requests/api/orbit/data_spec.rb.

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

References

Closes gitlab-org/orbit/knowledge-graph#514 (closed)

Merge request reports