GitHub API Authentication - Personal Access Tokens

#github #javascript #octokit

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.

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.

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.