GitLab · 2025 · Authorization

Fine-Grained Personal Access Tokens

GitLab's Personal Access Tokens granted all-or-nothing API access, creating serious blast radius risk when tokens were compromised. I led the end-to-end UX for a new fine-grained permissions model — running a full research program to resolve competing approaches and ship a system built for the era of AI agents acting on behalf of users.

Role
Lead Product Designer
Timeline
Jul 2025 – Feb 2026
Team
Authorization Engineering, AppSec, PM, TW
Status
Beta shipped · GA in progress
Hero image
Export from Figma at 2x, ~1400px wide
Overview Define Research Solution Outcomes
Overview
Tokens that gave too much away.

GitLab's Personal Access Tokens used coarse-grained scopes like read_api or api that granted access across GitLab's entire feature set. When a token was compromised, attackers gained access to everything the user could access across every group and project they belonged to.

The task was to design a new model that let users create tokens scoped to specific resources, permissions, and groups — following the principle of least privilege. With AI agents increasingly using PATs to act on behalf of developers, getting this right had long-term implications well beyond the immediate security problem.

Define
Three models. One hard question.

Before any usability testing, I defined six distinct user types with different security needs and mental models: system administrators, solo developers, open source contributors, freelancers, DevOps engineers, and enterprise users. Each had different expectations about how tokens should work.

I then developed three competing permission models for validation, each representing a different tradeoff between control and complexity.

Model Approach Tradeoff
Permission sets Predefined bundles of permissions grouped by category. User selects None, Read, or Read and Write per set. Easiest to use. Risk of over-permissioning if users select broad sets without reading descriptions.
Fully granular Full CRUD access across 300+ individual permissions. User picks and chooses exactly what each token can do. Maximum control for security teams. Overwhelming for general developers without guidance.
Multiple scopes User can create multiple permission entries per token, each scoped to different groups or projects. Powerful for complex workflows. High cognitive load, users preferred separate tokens instead.

The real design challenge was not which model to pick. It was how to serve a security engineer and a general developer with the same interface without compromising either.

Research
13 participants. Two months. One clear direction.

I ran moderated interviews and unmoderated usability tests across internal GitLab team members and external customers, including developers, security architects, solutions architects, and enterprise users.

01
Journey mapping and early alignment
Mapped the full PAT lifecycle across five stages: recognition, governance setup, creation, use, and ongoing maintenance. Shared low-fidelity mocks with the broader engineering and product team to align on requirements before investing in high-fidelity work.
02
High-fidelity prototypes for all three models
Built three interactive Figma prototypes and recorded a walkthrough video for async team review. Iterated based on feedback from engineering leads on inheritance logic, permission grouping feasibility, and LDAP compatibility before testing with users.
03
Moderated interviews with 13 participants
Ran sessions from August through September 2025. Mix of internal team members (solutions architects, security, support) and external developers. Shared early findings with engineering leads in real time to inform ongoing technical decisions running in parallel.
04
Synthesis and product decision
Published findings on September 22, product decision on September 23. Findings resolved the model debate and scoped GA requirements clearly.

Key findings:

Permission sets scored highest for ease of useGeneral developers preferred them. Security professionals wanted fine-grained control for compliance needs. The two audiences needed different entry points to the same system.
Multiple scopes per token had negative receptionUsers preferred creating separate tokens for different purposes rather than managing complex multi-scope tokens. The mental model of one token per use case was consistent across participants.
Templates and in-app guidance were essential, not optionalUsers wanted to learn within the application. Information modals directly correlated with confidence. Users had a test-and-iterate workflow, making the inability to edit tokens after creation a significant over-permissioning risk.
Naming inconsistencies caused confusionUsers struggled with naming variations in the fine-grained permission list. Clear, consistent resource naming became a core design requirement going into final specs.
Research — journey map or prototype comparison
Journey map, annotated prototype, or research synthesis
Solution
Fine-grained permissions, designed for two audiences.

The permission model. Moved forward with the fine-grained model as the primary path, with templates and simplified guidance planned for GA to bridge the complexity gap for general developers. Tab navigation separates group and project permissions from user and instance permissions, addressing an engineering feedback issue about scope confusion in the original layout.

Resource and permission layout. Two-column design with a resource selector on the left and permission definitions on the right. Resources organized by category with expand and collapse, each with an information popover. CRUD selectors per resource type. Empty state guides users to start selecting rather than confronting a blank form.

Token management system. Full lifecycle coverage: view token detail in a drawer, rotate, revoke, and duplicate. Duplicate pre-populates a new token form with the same permissions and scope, solving the "reuse without over-permissioning" problem users described. Safe revocation with modal confirmation, email notification, and table status updates.

Admin credential view. Admins can see fine-grained token scope in the credential inventory, giving security teams visibility into what access is actually in use across the organization.

Final designs — token creation form, permission selector, token management
Export from Figma at 2x, ~1400px wide
Outcomes
Built for today and for AI agents tomorrow.
13
Research participants
Internal and external across security, engineering, and developer roles. Findings drove the product direction decision within 24 hours of the report.
50%
Adoption target within 6 months
Product success metric for new PATs using the fine-grained model post-GA launch.
85%
Developer satisfaction target
Post-launch satisfaction score target set in success metrics, reflecting the dual audience design challenge.

The fine-grained PAT system is also foundational infrastructure for AI agent use cases. As engineers and security architects noted during research, AI agents acting on behalf of users need tokens scoped to exactly what they need for a given task. The permission model and resource scoping designed here directly enables that without requiring a separate system.

Next
Custom Admin Role
→