DEV Community

Gregor Martynus
Gregor Martynus

Posted on • Updated on

GitHub API Authentication - Personal Access Tokens

Personal Access Tokens are the easiest way to authenticate requests as a GitHub user. You can create a new Personal Access Token at https://github.com/settings/tokens/new.

Create a personal access token screenshot

Set the note to something memorable. The scopes are pretty self-explanatory, only select what you are sure you will need. The public_repo scope is what you'll need in most cases, e.g. to retrieve, create or update all things related to repositories.

The next screen will show you the token. Make sure to copy it somewhere safe as it won't be shown again.

Personal Access Token created screenshot

You can now use that token, for example to retrieve the latest release of octokit/core.js using curl from your terminal

curl --header "Authorization: token d64761df071c2bf517ceb063b279432ed2f89c62" \
     https://api.github.com/repos/octokit/core.js/releases/latest
Enter fullscreen mode Exit fullscreen mode

Or using fetch in a browser or node-fetch in Node.js

const response = await fetch(
  "https://api.github.com/repos/octokit/core.js/releases/latest", 
  {
    headers: {
      authorization: "token d64761df071c2bf517ceb063b279432ed2f89c62"
    }
  }
)
console.log(await response.json());
Enter fullscreen mode Exit fullscreen mode

Using the JavaScript Octokit

Authenticating using a personal access token is straight forward, so it's already built into https://github.com/octokit/core.js and all libraries that are built upon it.

Sending the above request would look like this in the browser

<script type="module">
import { Octokit } from "https://cdn.pika.dev/@octokit/core";

const octokit = new Octokit({ auth: "d64761df071c2bf517ceb063b279432ed2f89c62" });
octokit.request('GET /repos/:owner/:repo/releases/latest', {
  owner: "octokit",
  repo: "core.js"
}).then(response => console.log(response.data))
</script>
Enter fullscreen mode Exit fullscreen mode

And like this in Node.js

const { Octokit } = require('@octokit/rest')
const octokit = new Octokit({ auth: "d64761df071c2bf517ceb063b279432ed2f89c62" });
octokit.request('GET /repos/:owner/:repo/releases/latest', {
  owner: "octokit",
  repo: "core.js"
}).then(response => console.log(response.data))
Enter fullscreen mode Exit fullscreen mode

Handling errors

If the token is invalid, the server will respond with a 401 status and a "bad credentials" message

curl --header "Authorization: token invalid" https://api.github.com/notifications                                 
{
  "message": "Bad credentials",
  "documentation_url": "https://developer.github.com/v3"
}
Enter fullscreen mode Exit fullscreen mode

If the token does not have the required scopes, the server will respond with a 403 status and an explanatory message

curl --header "Authorization: token d64761df071c2bf517ceb063b279432ed2f89c62" https://api.github.com/notifications
{
  "message": "Missing the 'notifications' scope.",
  "documentation_url": "https://developer.github.com/v3/activity/notifications/#list-your-notifications"
}
Enter fullscreen mode Exit fullscreen mode

New scopes cannot be added to existing tokens, you will have to create a new token with the required scopes selected to address 403 errors.

Limitations

Personal Access Tokens work great for personal usage. But if you plan to create a service or a CLI application that integrate with GitHub, there are better options that don't require the user to manually create and maintain tokens. I will write about all of them in the remaining posts of this series.

Personal Access Tokens can be used in GitHub Actions if you want the script to act as your user account. Next week I'll talk about authenticating scripts run by GitHub Actions, and how to utilize the special GITHUB_TOKEN secret as a simpler alternative to using Personal Access Tokens for most cases.

Discussion (2)

Collapse
lumie31 profile image
Olumide

Thanks for this. I've been facing an issue of disappearing access token after committing my code to github. How do you think this can be solved?

Collapse
kunigami profile image
Guilherme Kunigami

Very helpful article, thanks! I can't believe how hard is to find this information on GitHub docs.