loading...

GitHub API Authentication - Personal Access Tokens

gr2m profile image Gregor Martynus Updated on ・3 min read

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

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());

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>

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))

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"
}

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"
}

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.

Posted on by:

gr2m profile

Gregor Martynus

@gr2m

Father of triplets Nico, Ada & Kian. Web developer with 20+ yrs experience. JavaScript Octokit Maintainer for GitHub. He/him

Discussion

pic
Editor guide
 

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