Setting up your Github OAuth app
A quick overview of how to setup a Github OAuth app
Prerequisites
Access to your company's main Github account or any account with privileges that can create and manage Github OAuth apps that will allow access to the repo containing the content for the api docs.
A Github repository specifically set up for API documentation.
Read and write access granted to all team members that will be accessing the portal to read, create and update API specifications.
Creating the OAuth app
Once you are logged in to a Github account with the correct privileges within your company, navigate to the settings page for the account.
You will be taken to a page that will look something like the following:
For the application name enter something like My Company Api Portal.
For the Homepage URL enter the the base url of where your instance of the portal will live such as https://apidocs.mycompanylabs.io.
Add a description in if you feel so inclined, this may be particularly beneficial if you have a lot of OAuth apps in your Github account or have different instances of apydox for different products your company builds.
The authorization callback will need to be https://apidocs.mycompanylabs.io/login/oauth/callback, the /login/oauth/callback here is really important as it is the route used in the portal that allows users to login to the portal with their github accounts by making a request to Github to create an access token given the a code. Check out the amazing documentation provided by Github themselves on how this flow works here: https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/
Click register application to create your brand new and exciting OAuth app.
You will need to take note of the client id and client secret of your OAuth app, these will be used as secrets in the api so it can deal with checking validity of access tokens, retrieving access tokens given an authorisation code and revoking access tokens when users logout.
Now we can move on to deploying your instance of the api.
Last updated
