Skip navigation
the word "security" in the middle of code Alamy

How to Use GitHub Personal Access Tokens

When it comes to managing access to GitHub resources, Personal Access Tokens have a number of benefits over passwords. This article explains why and how to generate a Personal Access Token for your GitHub account.

Although GitHub supports password-based authentication, a more secure means of controlling access to resources inside GitHub is to use Personal Access Tokens. Personal Access Tokens require more work to set up, but they offer a variety of benefits compared with conventional authentication.

This article explains how Personal Access Tokens work in GitHub, why you may want to use them, and how to generate a Personal Access Token for your GitHub account.

What Is a GitHub Personal Access Token?

In GitHub, a Personal Access Token is a way of authenticating with GitHub services without using passwords. Each user can generate a unique token, then define which types of actions — known in GitHub as "scopes" — can be performed based on that token.

Related: GitHub vs. GitLab: Which One Is Better for Your Enterprise?

You can also authenticate with GitHub using a password. However, as explained below, token-based authentication offers a number of benefits, such as the abilities to configure access rights in a more granular way and to grant access for a limited amount of time.

How to Generate a Personal Access Token

Creating Personal Access Tokens in GitHub is straightforward:

1. Click your portfolio button on any page in GitHub, then press the Settings button.

2. Navigate to Developer Settings>Personal access tokens.

3. On the screen that loads, click the Generate new token button, give your token a name, and configure the expiration period for the token.

4. Configure which scopes to assign to the token. We'll explain what scopes mean in detail below, but basically, they are the specific types of permissions that the token should allow a user to perform.

5. When the configuration process is complete, click the Generate token button to activate your new token.

Using a Personal Access Token

Once you've created a token, you can enter it in the password field when prompted for a password within either the GitHub web interface or on the CLI. Note that GitHub may explicitly ask for a "password," but you can still enter a token in most cases.

Related: GitHub Desktop 3.0 Improves DevOps Collaboration

However, you'll only be able to log in successfully with your token if you configured a scope that grants you permission to access whichever resource you are trying to access, or whichever action you are trying to perform. So, you may find that your token serves as an alternative to a GitHub password in some cases, but not in others, depending on what you are trying to accomplish.

Note, too, that because your web browser might cache login information for GitHub, you may need to clear your browser's cache to use a token. Otherwise, GitHub will continue using the password-based login that is stored in the cache instead of giving you a prompt where you can enter a token.

What Are the Benefits of Using a GitHub Personal Access Token?

Compared with passwords, Personal Access Tokens offer several key benefits:

  • Granular security settings: Because you can select specific scopes for each token, tokens can be used to define granular permissions. In other words, you can create tokens that grant access to some GitHub actions or services but not others. You can't do this with passwords.
  • Predefined expiration: You can configure tokens to expire at a predefined time. This is convenient if you want to grant a GitHub user temporary access to a resource. For instance, you may want to allow the cloning of a repository on a temporary basis, but not allow permanent access.
  • Randomization: Because tokens are totally random strings of significant length, attackers effectively can't "steal" them using brute-force or dictionary attacks. Passwords may be susceptible to such attacks if they are not sufficiently complex.
  • Faster login: The login process using tokens is faster because it requires less computation. Although this is not likely to make a major difference for logins by humans, it may be advantageous if you are, for instance, running scripts where you need to authenticate with GitHub repeatedly, and saving just fractions of a second on each login will add up to a significant reduction in overall runtime.

There's certainly no requirement to use tokens on GitHub, but from the perspective of security, performance, and control, tokens are more advantageous than passwords.

Understanding Scopes for Personal Access Tokens

As noted above, Personal Access Tokens can be configured to grant different "scopes." Scopes are the specific permissions that a token allows a user to perform. Scopes can be used to allow users to perform certain actions or download or modify certain data from GitHub.

For example, if you want to create a token that lets a user manage the teams, projects, and memberships inside a GitHub organization, you can grant the admin:org scope. But if you want to restrict the user to viewing information about teams, projects, and memberships without being able to modify it, you could grant the read:org scope, which provides read-only access.

If you don't define any scopes, tokens grant read-only access to public resources available on GitHub. So, tokens without associated scopes don't allow users to do anything they couldn't already do on GitHub without authenticating at all, since publicly available resources are viewable by default for everyone.

The full set of available scopes is described in GitHub's documentation. You'll also see a summary of available scopes when you configure a Personal Access Token in the GitHub interface.

What Is the Expiration Time for a Personal Access Token?

The expiration period for a Personal Access Token — meaning the point at which the token can no longer be used — depends on which period you configure when you create the token. You can select expiration periods based on fixed periods of time, like one year or one week. Or, you can choose a specific expiration date from a calendar.

Note, however, that if you choose to revoke a token before its expiration date, the token will expire and no longer be usable, even if the expiration period you set when creating the token has not yet run out.

You can also change the expiration period for an existing token on the Personal Access Tokens settings page.

How Do You Delete a Personal Access Token?

The process for deleting a Personal Access Token is a bit more complicated than creating one, but it is possible to delete tokens.

To delete a Personal Access Token, navigate to Settings>Applications>Authorized OAuth Apps. From there, you can select applications whose authorization permissions you want to revoke. Tokens associated with the applications will be revoked as well.

You can also simply change the token expiration date so that it expires immediately. This isn't quite the same as deleting the token, but it effectively results in the same outcome: The token becomes unusable.

Are There Any Security Risks Associated with Using a Personal Access Token?

Although Personal Access Tokens are more secure in certain respects than passwords, it's important to keep in mind that tokens can still be abused.

Anyone who gains access to your token, and who also knows the usernames associated with the token, will be able to use the token to authenticate with GitHub just like you could. So, you should protect your tokens in the same way that you protect passwords.

That said, the fact that tokens can be revoked quickly means that you can easily make a token unusable if it falls into the wrong hands while still being able to use other tokens or your password to connect to GitHub. This is easier than having to reset your password in the event that it is stolen.

Can I Use My Personal Access Token to Give Someone Else Access to My Account?

Since Personal Access Tokens function like passwords, you can use them to give other people access to your GitHub account. Indeed, tokens can be a useful means of providing someone with limited access to certain resources or with certain permissions.

For example, you may want to allow someone to view code in a private repository but not modify it. You could do this using tokens. But you would not want to attempt this by sharing your password because someone with your password would have unrestricted access to everything inside your GitHub account.

Security Edge Goes to Personal Access Tokens

Because Personal Access Tokens can be used to grant limited permissions, they are a more secure way of managing access to GitHub resources than passwords. They're also relatively easy to set up — although not as simple as configuring a password, which is something that happens when you sign up for GitHub. And the fact that you can easily revoke tokens when they are no longer necessary adds a layer of security that you won't obtain from passwords.

About the author

Christopher Tozzi headshotChristopher Tozzi is a technology analyst with subject matter expertise in cloud computing, application development, open source software, virtualization, containers and more. He also lectures at a major university in the Albany, New York, area. His book, “For Fun and Profit: A History of the Free and Open Source Software Revolution,” was published by MIT Press.
Hide comments

Comments

  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
Publish