Tighter credential controls for GitHub API and git access
Compromised credentials remain the leading cause of data breaches, and GitHub has historically responded with measures like mobile 2FA, WebAuthn security key support, and push protection for Advanced Security customers. But even with strong authentication, limiting what a valid credential can do is equally important. Until now, personal access tokens (PATs) offered only coarse-grained permissions: a token could reach everything the owning user could access, with no visibility or control for organization administrators.
That changes today with the introduction of fine-grained personal access tokens, now in Public Beta. These new tokens let developers specify both the exact repositories and the specific permissions a token may use. Organization owners get approval workflows and an audit view for tokens touching their resources. Existing tokens remain fully supported and are now referred to as personal access tokens (classic).
What fine-grained tokens change
PATs are commonly used to call the GitHub REST API and to authenticate git connections over HTTPS, particularly for scripts and integration testing. Classic PATs draw from broad read/write scopes — the repo scope, for instance, grants perpetual access to every private repository the user can reach. Fine-grained tokens instead use a set of more than 50 granular permissions covering organization, user, and repository APIs. Each permission can be set to no access, read, or read and write. A token can, for example, read issues only, with no ability to view repository contents.
Fine-grained tokens also differ in lifespan and reach. They are required to expire and are restricted to the specific repositories or organizations they are granted to, rather than inheriting all of the owner’s accessible resources. Tokens can even be scoped to a single repository within an organization.
New tokens are created from the Developer Settings section of account settings:
The permissions and repository targeting available to fine-grained PATs mirror those of GitHub Apps, which eases the path from quick scripts to production-grade integrations.
Organization and enterprise oversight
Classic PATs historically gave organization and enterprise administrators no direct control. Fine-grained PATs introduce a Personal Access Tokens tab in Organization Settings where owners can:
- Approve tokens — By default, each fine-grained PAT targeting an organization or its repositories requires owner approval.
- View and revoke — Owners can audit previously granted tokens and revoke access as needed. Classic PATs offer a comparable feature but only for organizations using SAML SSO.
- Block classic PATs — Organizations can forbid classic PAT use entirely, with some trade-offs noted below.
Enterprise owners can also set policies across all organizations via a new Personal Access Tokens page under the Policies tab.
Choosing the right method
GitHub recommends fine-grained PATs over classic PATs wherever possible, since the reduced permission and repository scope limits the blast radius of a stolen credential. However, fine-grained tokens do not yet cover every use case. Access to organizations the token owner is not a member of — which covers some open source and innersource contributions — still requires a classic PAT. Calling enterprise account APIs likewise requires a classic token or an OAuth app.
For long-running automation, GitHub suggests GitHub Actions or GitHub Apps. Apps offer the same fine-grained permissions and administrative controls as fine-grained PATs, persist independent of any individual employee, and are not tied to a user who may leave the organization.
Current limitations and roadmap
Fine-grained PATs are available now for all users, organizations, and enterprises on GitHub.com. During the beta, several gaps remain that GitHub intends to close before general availability:
- REST API support only — GraphQL is not yet supported for fine-grained PATs.
- Tokens can currently target repositories in only one organization, and cannot target resources outside the token owner’s memberships.
Some REST endpoints still require classic PAT or OAuth scopes; endpoint-level permission details are documented in GitHub’s API reference. Administrators should also expect policy management APIs for approving and revoking tokens at scale in future releases.
For organizations, fine-grained PAT use is opt-in during the beta. Owners can enable it, set approval requirements, and restrict classic PATs from the new Personal access tokens page in Organization Settings. Enterprise owners have equivalent policy controls. Users can begin creating fine-grained tokens immediately in Developer Settings, with access to personal repositories and to any organizations that have opted in.
