<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/engineering/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=40916776&issueIid=6868) - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=40916776&issueIid=6868) </details> <!--IssueSummary end--> ## Feature [Fine-grained personal access tokens](https://docs.gitlab.com/auth/tokens/fine_grained_access_tokens/) went beta in GitLab 18.10 and GA in 19.2. Instead of the flat `scopes` list, they are defined by *granular scopes*: an `access` boundary (`user`, `instance`, `all_memberships`, `personal_projects`, `selected_memberships`) plus a list of permissions, optionally targeting specific groups or projects. The provider currently only supports legacy scopes. `gitlab_personal_access_token` exposes a `scopes` set validated against the classic scope list (`api`, `read_api`, `self_rotate`, ...), so fine-grained tokens can only be created in the UI, and a token created there cannot be represented in Terraform. An example of what this might look like: ```hcl resource "gitlab_personal_access_token" "example" { user_id = 42 name = "fine-grained-token" expires_at = "2027-01-01" granular_scope { access = "selected_memberships" permissions = ["read_job"] project_ids = [6] } granular_scope { access = "user" permissions = ["read_user"] } } ``` with `scopes` and `granular_scope` being mutually exclusive. If this lands for personal access tokens, the same treatment would presumably be wanted later for group/project access tokens, but the feature is personal-access-token-only today (there is no granular support in `lib/api/group_access_tokens.rb`, `lib/api/project_access_tokens.rb` or `lib/api/resource_access_tokens.rb`). ## Related GitLab APIs API documentation: - **Read**: [`GET /personal_access_tokens`](https://docs.gitlab.com/api/personal_access_tokens/#list-all-personal-access-tokens) and `GET /personal_access_tokens/:id` return a `granular_scopes` array of `{access, permissions, project_id, group_id}`, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/589500) in GitLab 19.2. - **Rotate**: [`POST /personal_access_tokens/:id/rotate`](https://docs.gitlab.com/api/personal_access_tokens/#rotate-a-personal-access-token) carries the granular scopes over to the new token and returns them. - **Revoke**: `DELETE /personal_access_tokens/:id`, unchanged. - **Create**: [`POST /user/personal_access_tokens`](https://docs.gitlab.com/api/user_tokens/#create-a-personal-access-token) accepts a `granular_scopes` array, `exactly_one_of :scopes, :granular_scopes`. This is not in the prose documentation yet — it is only visible in the generated OpenAPI spec and in the source (`lib/api/users.rb`, `lib/api/helpers/personal_access_tokens_helpers.rb`). Added in [`b76ed9e8be8d`](https://gitlab.com/gitlab-org/gitlab/-/commit/b76ed9e8be8dba28b0b447fe85655a55a73fd59b) ("Add REST support for creating granular PATs", 2026-07-08) and present in `v19.2.0-ee`. The parameter shape is: ```ruby optional :granular_scopes, type: Array do requires :access, type: String, values: GRANULAR_SCOPE_ACCESS_VALUES requires :permissions, type: Array[String] optional :project_ids, type: Array[Integer] # when access is selected_memberships optional :group_ids, type: Array[Integer] end ``` Note that the `k8s_proxy`/`self_rotate` restriction on this endpoint applies only to the classic `scopes` parameter; granular scopes are not restricted there. So REST is sufficient for full CRUD of granular tokens — with one gap, below. GraphQL (`Mutation.personalAccessTokenCreate`, GitLab 18.7, Status: Experiment) also exists, but should not be needed. ### Gap: no granular support on the admin create endpoint `POST /users/:user_id/personal_access_tokens` — creating a token for *another* user, administrators only — was not updated and still has `requires :scopes` with no granular parameter. That is the endpoint this resource uses today (`r.client.Users.CreatePersonalAccessToken(user_id, ...)`), because `gitlab_personal_access_token` is keyed on `user_id`. As it stands, the provider could therefore only create granular tokens for the user the provider itself is authenticated as, via `POST /user/personal_access_tokens`, which is a somewhat awkward split in behaviour between the two scope modes. This gap is already being closed upstream: gitlab-org/gitlab!245585 ("Add granular scope support to admin create-token-for-user endpoint") adds `granular_scopes` to `POST /users/:user_id/personal_access_tokens`, explicitly to match the self endpoint and the impersonation endpoint. It is open, not a draft, and milestoned **19.3**. Once it merges, this resource can support granular scopes through REST in exactly the same shape it supports `scopes` today, on the endpoint it already calls. There is also a documentation gap: `doc/api/user_tokens.md` does not currently mention `granular_scopes` at all, so the existing create support is easy to miss. That MR updates the API documentation as well. ## Additional Details - [x] [GitLab REST API resources](https://docs.gitlab.com/api/api_resources/) available (*read* for data sources, *CRUD* for resources) — read, create (self), rotate and revoke are all REST; the admin create-for-another-user path is pending in gitlab-org/gitlab!245585 (milestone 19.3) - [ ] [client-go](https://gitlab.com/gitlab-org/api/client-go) supports the related GitLab API already — no, `v2.47.0` has no granular scope fields at all (`CreatePersonalAccessTokenOptions` is `Name`/`Description`/`ExpiresAt`/`Scopes`, and `PersonalAccessToken` has no `GranularScopes`), so a small upstream MR is needed first - [ ] I'd like to contribute it myself One more caveat: granular personal access tokens are gated behind the `granular_personal_access_tokens` feature flag, which is `type: beta` but `default_enabled: true` since 18.7. The create endpoint returns `404` when it is disabled, so the provider would need to surface that clearly. For context, this is related to but distinct from #6625 (fine-grained permissions for the CI/CD job token allowlist). That one is blocked on experimental GraphQL; this one is not, since the REST endpoints described above are generally available.