GitHub API Authentication - Introduction

This is the first post of a series about different Authentication strategies for GitHub's APIs. The different strategies that I plan to write about are

1. Personal Access Tokens
2. GitHub Actions
3. Username & Password (Basic)
4. OAuth
5. Webhooks
6. GitHub Apps
7. CLI

Authenticating requests is required for GitHub's GraphQL API and strongly encouraged for GitHub's REST API.

While it is possible to send unauthenticated REST API requests, only 60 requests per hour are permitted. Unauthenticated requests are rate limited based on IP addresses, so if you sent them from virtual servers such as most CI environments they are likely depleted most of the time.

Example

Sending an anonymous request responds with X-RateLimit-* headers stating that less than 60 more requests can be sent until the rate limit is reset. For this example, I'm using curl

curl --head https://api.github.com/repos/octokit/core.js/releases/latest
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1578690442

Sending the same request with an authorization header shows the increased rate limit

curl --head \
     --header "Authorization: token 70e98949b567d678f62ed81866a1cd54aaeee400" \
     https://api.github.com/repos/octokit/core.js/releases/latest
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1578690903

The string 70e98949b567d678f62ed81866a1cd54aaeee400 is an example of a personal access token, which I wrote about in the next post of this series.

Comments

[Shravan Kumar B]

@gr2m: Nice writing, really gave me overview on auth for github. :)

I have a couple of doubts:

1. I am doing oauth with github, to you allow access via github APIs via the user's access_token. But I see that the overall rate limit is still 5k despite using access_token received after authentication. Why is that? Is there a way to increase this? Asking this since docs says we can increase our rate limit to 15k/hr if we use the access_token mechanism, but it doesn't seem to work. Any guidance here would be of great help.

2. I don't see any refresh tokens as part of the response, so in case the access_token expires how would we fetch the new token to extend the user session?

Thanks in advance!

[Liran Tal]

Gregor, thanks for writing this. Maybe you want to update the broken link at the end of the post that points to the next post of this series.

[Gregor Martynus]

fixed, thank you! I wonder how that broke 🤔

[Lucia Cerchie]

Thanks Gregor! This helped me figure out how to authenticate for my app :)