Suggestions for clarifying API documentation for Github Apps?


#1

I’m working on building a GitHub app and have run into two issues that I wanted to suggest could be clarified in the documentation. On the second item, I am not sure if I am misunderstanding the docs or not, so I’m happy to be corrected!

OAuth Scope

While building the OAuth flow for my GitHub App, I was mostly looking at the OAuth documentation under the OAuth App section of the docs. I spent quite a bit of time trying to debug and figure out why the scopes I was setting weren’t resulting in access tokens that had those permissions. It wasn’t until later that I came across the Identifying and authorizing users for GitHub Apps docs and the fine print:

Note: You don’t need to provide scopes in your authorization request. Unlike traditional OAuth, the authorization token is limited to the permissions associated with your GitHub App and those of the user.

My suggestion would be to include some call-outs in all of the OAuth flow docs, including those under OAuth Apps, that mention this and link to the specific documentation for Github Apps. A message like: “Building a Github App? Read about how scopes work.”

Accessing API as Github App versus an installation

Authentication options for GitHub Apps describes how to authenticate as a Github App, as well as how to get an installation access token with which to make API requests “as an installation”.

The page links out to:

However, this information seems to be a bit misleading. For example, I am NOT able to access the List pull requests endpoint using a Github App jwt token. It seems I can only access it using an installation access token?

If this is in fact the case, my suggestion would be to reorganize the docs a bit so that endpoints that require an installation access token are clearly indicated and organized as such.


#2

I’ll second this, especially the need for clarity on what type of authentication is required for each of the endpoints, it’s not clear what has to be done as a user under conventional oauth, what can be done as an app with a jwt_token, and what can/must be done with an installation_token.


#3

Thanks for taking the time to make those suggestions @abinoda. I agree there is room to improve the documentation experience here.

I like both of your suggestions, and I’ll pass them along to our documentation team for consideration.

For example, I am NOT able to access the List pull requests endpoint using a Github App jwt token. It seems I can only access it using an installation access token?

The List pull requests endpoint should work with both a server-to-server JWT token and a user-to-server OAuth token. I :100: agree that adding more clarification on which endpoints are enabled for which authentication mechanisms is something we should look to add.


#4

Thanks @jmilas. I’ll try that “List pull requests” with the JWT token and let you know if I run into any trouble!