GitHub API Authentication - Personal Access Tokens
Tags: github, javascript, octokit
Published: 2020-01-10 23:44:53

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](https://thepracticaldev.s3.amazonaws.com/i/hua76w8dz9qh7zhpvzk1.png)

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](https://thepracticaldev.s3.amazonaws.com/i/mfz56rp2vawjv5aarswe.png)

You can now use that token, for example to retrieve the latest release of [octokit/core.js](https://github.com/octokit/core.js) using [curl](https://curl.haxx.se/) from your terminal

```shell
curl --header "Authorization: token d64761df071c2bf517ceb063b279432ed2f89c62" \
     https://api.github.com/repos/octokit/core.js/releases/latest
```

Or using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) in a browser or [node-fetch](https://github.com/bitinn/node-fetch/) in Node.js

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

```html
<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

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

```shell
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

```shell
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](https://github.com/features/actions), and how to utilize the special [GITHUB_TOKEN secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token) as a simpler alternative to using Personal Access Tokens for most cases.