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.
Top comments (3)
👍
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?
Very helpful article, thanks! I can't believe how hard is to find this information on GitHub docs.