Improve fine-grained PAT self-introspection

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Summary

Review and improve the self-inform API behavior for fine-grained Personal Access Tokens (PATs), so integrations can determine the token’s permissions without requiring broader access or making multiple API calls.

Context

Integration feedback identified two issues:

  • The self-inform API currently requires the read_personal_access_token scope.
  • The self-inform response does not appear to provide the same information as GET /personal_access_tokens/:id, including granular_scopes, which can require an integration to make a second request.

The permission check may be intentional for compatibility with legacy tokens, so this issue should first establish the desired behavior for legacy and fine-grained PATs before changing the API contract.

Problem

A token should be able to report its own effective identity and permissions without requiring permission to read Personal Access Token details more broadly. Requiring read_personal_access_token can make a least-privilege integration harder to configure. If the self-inform response omits granular permissions, integrations also need an additional request and more complex fallback logic.

Proposed outcome

Define and implement a consistent, least-privilege self-introspection experience for PATs:

  • Confirm whether self-introspection should work without read_personal_access_token, or whether a separate dedicated introspection permission is more appropriate.
  • Return the granular permission information needed by integrations, including granular_scopes, where it is safe and applicable.
  • Preserve compatibility for legacy PATs and clearly define any differences between legacy and fine-grained tokens.
  • Update API documentation and examples so integrations can determine which endpoint and permission are required.

Acceptance criteria

  • A documented behavior matrix exists for legacy PATs and fine-grained PATs, covering the self-inform API, read_personal_access_token, and granular permission visibility.
  • The chosen self-introspection model follows least privilege and does not grant access to unrelated PATs.
  • An integration can obtain the token’s granular permissions through the documented self-introspection flow without an unnecessary second request.
  • Automated tests cover permitted and denied requests for both legacy and fine-grained PATs.
  • API documentation explains the response fields, required permissions, compatibility behavior, and migration guidance.

Open questions

  • Is the current read_personal_access_token requirement needed for fine-grained PATs, or only for legacy-token compatibility?
  • Should self-introspection always be available for the token being used, or should it require a dedicated scope?
  • Is the difference in returned fields intentional, or is granular_scopes missing from the self-inform response?

References

Edited by 🤖 GitLab Bot 🤖