GitHub, like all OAuth based APIs, requires that each request to the API made on behalf of a user is authenticated with an access_token
. If you don't pass an access_token
alongside your request, the request will fail with a 401 Unauthorized
status code.
There's no way to ask GitHub if a random user has accepted your app. It's not something implemented in the OAuth framework - as it could lead to a security flaw. So it's your responsibility as the application's owner to record which user has authorized your app.
With this in mind, let's try to sum up the differents steps that Heroku had to achieve to display this "Connected" status under the GitHub logo.
- When you've signed-up on Heroku, the status of the GitHub integration was "not_connected". If you visit the settings page, you would see a "Connect to GitHub" button.
- At some point, in the Heroku dashboard, you have clicked on the "Connect to GitHub" button and have authorized Heroku's app for GitHub. This is where you've been redirected to the
callback_url
- At this particular time, while you were on the
callback_url
page, Heroku has recorded in its database the new status of the GitHub integration for your account. It was set to "connected". Heroku has probably saved alongside the access_token
and refresh_token
.
- Every time that you visit the settings page of your app, Heroku can render that you are connected because it has the status in its database.
- (optional) When Heroku performs requests to the GitHub API using your
access_token
it can confirm that the connection is still live. If ever the request failed with a 401 Unauthorized
, Heroku can update its database and reset your GitHub integration status to "not_connected".
This work like this for the GitHub API, as well as with any other OAuth based APIs. If you plan to integrate with several APIs, I highly recommend you to use an API Integrations Manager, such as Pizzly. It will help you focus on the business logic ("is my user connected or not?") and totally handle the OAuth process for you.