Managing your personal access tokens

About personal access tokens

Personal access tokens are an alternative to using passwords for authentication to GitHub when using the GitHub API or the command line.

Personal access tokens are intended to access GitHub resources on behalf of yourself. To access resources on behalf of an organization, or for long-lived integrations, you should use a GitHub App. For more information, see About creating GitHub Apps.

A token has the same capabilities to access resources and perform actions on those resources that the owner of the token has, and is further limited by any scopes or permissions granted to the token. A token cannot grant additional access capabilities to a user. For example, a personal access token can be configured with an admin:org scope, but if the owner of the token is not an organization owner, the token will not give administrative access to the organization.

Types of personal access tokens

GitHub currently supports two types of personal access tokens: fine-grained personal access tokens and personal access tokens (classic). GitHub recommends that you use fine-grained personal access tokens instead of personal access tokens (classic) whenever possible.

Both fine-grained personal access tokens and personal access tokens (classic) are tied to the user who generated them and will become inactive if the user loses access to the resource.

Organization owners can set a policy to restrict the access of personal access tokens (classic) to their organization, and enterprise owners can restrict the access of personal access tokens (classic) to the enterprise or organizations owned by the enterprise. For more information, see Setting a personal access token policy for your organization.

Fine-grained personal access tokens

Fine-grained personal access tokens have several security advantages over personal access tokens (classic), but also have limitations that may prevent you from using them in every scenario. These limits, and our plans to fix them, can be found in the section below.

If you can use a fine-grained personal access token for your scenario, you'll benefit from these improvements:

• Each token is limited to access resources owned by a single user or organization.
• Each token can be further limited to only access specific repositories for that user or organization.
• Each token is granted specific, fine-grained permissions, which offer more control than the scopes granted to personal access tokens (classic).
• Organization owners can require approval for any fine-grained personal access tokens that can access resources in the organization.
• Enterprise owners can require approval for any fine-grained personal access tokens that can access resources in organizations owned by the enterprise.

Fine-grained personal access tokens limitations

Fine-grained personal access tokens do not support every feature of personal access tokens (classic). These feature gaps are not permanent - GitHub is working to close them. You can review our public roadmap for more details on when these scenarios will be supported.

The major gaps in fine-grained personal access tokens are:

• Using fine-grained personal access token to contribute to public repos where the user is not a member.
• Using fine-grained personal access token to contribute to repositories where the user is an outside or repository collaborator.
• Using fine-grained personal access token to access multiple organizations at once.
• Using fine-grained personal access token to access internal resources within an enterprise the user belongs to.
• Using fine-grained personal access token to call APIs that manage the Enterprise account.
• Using fine-grained personal access token to access Packages.
• Using fine-grained personal access token to call the Checks API.
• Using fine-grained personal access token to access Projects owned by a user account.

All of these gaps will be solved over time, as GitHub continues to invest in more secure access patterns.

Personal access tokens (classic)

Personal access tokens (classic) are less secure. However, some features currently will only work with personal access tokens (classic):

• Only personal access tokens (classic) have write access for public repositories that are not owned by you or an organization that you are not a member of.
• Only personal access tokens (classic) automatically have write access for internal repositories that are owned by your enterprise. Fine-grained personal access tokens must be granted access to internal repositories.
• Outside collaborators can only use personal access tokens (classic) to access organization repositories that they are a collaborator on.
• Only personal access tokens (classic) can access enterprises. (Fine-grained personal access token can access organizations owned by enterprises.)
• A few REST API endpoints are only available with a personal access tokens (classic). To check whether an endpoint also supports fine-grained personal access tokens, see the documentation for that endpoint, or see Endpoints available for fine-grained personal access tokens.

If you choose to use a personal access token (classic), keep in mind that it will grant access to all repositories within the organizations that you have access to, as well as all personal repositories in your personal account.

As a security precaution, GitHub automatically removes personal access tokens that haven't been used in a year. To provide additional security, we highly recommend adding an expiration to your personal access tokens.

Keeping your personal access tokens secure

Personal access tokens are like passwords, and they share the same inherent security risks. Before creating a new personal access token, consider if there is a more secure method of authentication available to you:

• To access GitHub from the command line, you can use GitHub CLI or Git Credential Manager instead of creating a personal access token.
• When using a personal access token in a GitHub Actions workflow, consider whether you can use the built-in GITHUB_TOKEN instead. For more information, see Use GITHUB_TOKEN for authentication in workflows.

If these options are not possible, and you must create a personal access token, consider using another CLI service to store your token securely.

When using a personal access token in a script, you can store your token as a secret and run your script through GitHub Actions. For more information, see Using secrets in GitHub Actions. You can also store your token as a Codespaces secret and run your script in Codespaces. For more information, see Managing your account-specific secrets for GitHub Codespaces.

For more information about best practices, see Keeping your API credentials secure.

Creating a fine-grained personal access token

1. Verify your email address, if it hasn't been verified yet.

2. In the upper-right corner of any page on GitHub, click your profile picture, then click Settings.

3. In the left sidebar, click Developer settings.

4. In the left sidebar, under Personal access tokens, click Fine-grained tokens.

5. Click Generate new token.

6. Under Token name, enter a name for the token.

7. Under Expiration, select an expiration for the token. Infinite lifetimes are allowed but may be blocked by a maximum lifetime policy set by your organization or enterprise owner. For more information, See Enforcing a maximum lifetime policy for personal access tokens.

8. Optionally, under Description, add a note to describe the purpose of the token.

9. Under Resource owner, select a resource owner. The token will only be able to access resources owned by the selected resource owner. Organizations that you are a member of will not appear if the organization has blocked the use of fine-grained personal access tokens. For more information, see