Repository navigation
Please clean up documentation for /authorizations #19279
Description
Activity
@jsoref Thanks so much for opening an issue and providing all this detail! I'll triage this for the team to take a look 👀
@jsoref Thanks for this input! I agree that we need better authentication docs, and we are discussing ideas with the team. To make sure I understand what you are asking:
- Does Basics of authentication cover what you are looking for?
- Would it be clearer to combine Other authentication methods and Basics of authentication into a single article?
- The using-the-oauth-authorizations-api-with-two-factor-authentication section that you link to only applies to GHES. Many of our docs contributors are not GHES users, so I want to confirm that this was linked intentionally.
- Can you explain more about what you mean by
And it's mentioned in the /meta docs?
Does Basics of authentication cover what you are looking for?
No.
I'm really trying to figure out what permissions my
GITHUB_TOKENhas. And I have no idea how to do that.Would it be clearer to combine Other authentication methods and Basics of authentication into a single article?
I, personally, don't think having
Other authentication methodsas a separate article adds much value. So, I guess? (This is a really weak "yes")The using-the-oauth-authorizations-api-with-two-factor-authentication section that you link to only applies to GHES. Many of our docs contributors are not GHES users, so I want to confirm that this was linked intentionally.
It's linked because it was the only page that mentions it other than the meta page which shows it in the response. And yes, I'm aware it's in an
if. But, it was the only thing. No, I'm not a GHES user. But if I'm trying to understand how a thing works and the only thing that mentions it is a GHES doc, I'll still read and reference it. I won't expect it to be accurate to my use case, but what choice do I have?Can you explain more about what you mean by And it's mentioned in the /meta docs?
Here's the
meta docspage:
https://github.com/proxy/docs.github.com/en/rest/meta#github-api-root
the url is provided as a property of the response object for https://github.com/proxy/api.github.com/
{ ... "authorizations_url": "https://github.com/proxy/api.github.com/authorizations", ... }To quote Google: "That’s all we know."
Thanks for this additional detail.
The
/authorizationsendpoint is documented at https://github.com/proxy/docs.github.com/en/rest/oauth-authorizations. Note: That endpoint is deprecated for non-GHES users, and the non-GHES docs are scheduled to disappear in the very near future.For your question about
GITHUB_TOKEN, I think that https://github.com/proxy/docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token will help. (If you have suggestions for improvement for that article, please open a separate issue so that it doesn't get lost in this issue.) I can make a note for us to add a link from the REST authentication docs to the docs aboutGITHUB_TOKENto make that more discoverable.Does this answer your questions?
As you've noted that the
/authorizationsendpoint is gone, shouldn't the/metaendpoint on GitHub (and the docs for the same) not mention it (conditional on NOT GHES)?Similarly, shouldn't the https://github.com/proxy/docs.github.com/en/rest/oauth-authorizations#list-your-authorizations page no longer list it, as opposed to
https://github.com/proxy/docs.github.com/en/enterprise-server@3.2/rest/oauth-authorizations#list-your-authorizations
...
https://github.com/proxy/docs.github.com/en/enterprise-server@3.6/rest/oauth-authorizations#list-your-authorizationswhich can legitimately list it until they disappear...
- changed the title
[-]Please document `/authorizations`[/-][+]Please clean up documentation for `/authorizations`[/+]on Jul 26, 2022 9 remaining items
- Reacted by cmwilson21
We've consolidated the REST API authentication info into a single article. We've also raised the issue of the
/authorizationsfull removal with the team. It sounds like the root problem that you really want to identify is what permissionsGITHUB_TOKENhas. Since you don't own the GitHub App that is GitHub Actions, I don't think you will be able to use the API to programmatically see what permissions the built-in GITHUB_TOKEN has. I think we've addressed most of what this issue was opened for the best that we can. If there are additional things that you think should be addressed, please feel free to open another issue targeting those specific things.Reacted by Josh Soref
Code of Conduct
What article on docs.github.com is affected?
https://github.com/github/docs/blob/61b260231c18d4ad15f1663087c912025b48ac71/content/rest/overview/index.md
Basically, there should be a page that directly covers
/authorizations.It is indirectly mentioned here:
https://github.com/github/docs/blob/61b260231c18d4ad15f1663087c912025b48ac71/content/rest/overview/other-authentication-methods.md#using-the-oauth-authorizations-api-with-two-factor-authentication
And it's mentioned in the
/metadocs -- https://github.com/proxy/docs.github.com/en/rest/meta#github-api-rootResponse
{ "current_user_url": "https://github.com/proxy/api.github.com/user", "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}", "authorizations_url": "https://github.com/proxy/api.github.com/authorizations", "code_search_url": "https://github.com/proxy/api.github.com/search/code?q={query}{&page,per_page,sort,order}", "commit_search_url": "https://github.com/proxy/api.github.com/search/commits?q={query}{&page,per_page,sort,order}", "emails_url": "https://github.com/proxy/api.github.com/user/emails", "emojis_url": "https://github.com/proxy/api.github.com/emojis", "events_url": "https://github.com/proxy/api.github.com/events", "feeds_url": "https://github.com/proxy/api.github.com/feeds", "followers_url": "https://github.com/proxy/api.github.com/user/followers", "following_url": "https://github.com/proxy/api.github.com/user/following{/target}", "gists_url": "https://github.com/proxy/api.github.com/gists{/gist_id}", "hub_url": "https://github.com/proxy/api.github.com/hub", "issue_search_url": "https://github.com/proxy/api.github.com/search/issues?q={query}{&page,per_page,sort,order}", "issues_url": "https://github.com/proxy/api.github.com/issues", "keys_url": "https://github.com/proxy/api.github.com/user/keys", "label_search_url": "https://github.com/proxy/api.github.com/search/labels?q={query}&repository_id={repository_id}{&page,per_page}", "notifications_url": "https://github.com/proxy/api.github.com/notifications", "organization_url": "https://github.com/proxy/api.github.com/orgs/{org}", "organization_repositories_url": "https://github.com/proxy/api.github.com/orgs/{org}/repos{?type,page,per_page,sort}", "organization_teams_url": "https://github.com/proxy/api.github.com/orgs/{org}/teams", "public_gists_url": "https://github.com/proxy/api.github.com/gists/public", "rate_limit_url": "https://github.com/proxy/api.github.com/rate_limit", "repository_url": "https://github.com/proxy/api.github.com/repos/{owner}/{repo}", "repository_search_url": "https://github.com/proxy/api.github.com/search/repositories?q={query}{&page,per_page,sort,order}", "current_user_repositories_url": "https://github.com/proxy/api.github.com/user/repos{?type,page,per_page,sort}", "starred_url": "https://github.com/proxy/api.github.com/user/starred{/owner}{/repo}", "starred_gists_url": "https://github.com/proxy/api.github.com/gists/starred", "topic_search_url": "https://github.com/proxy/api.github.com/search/topics?q={query}{&page,per_page}", "user_url": "https://github.com/proxy/api.github.com/users/{user}", "user_organizations_url": "https://github.com/proxy/api.github.com/user/orgs", "user_repositories_url": "https://github.com/proxy/api.github.com/users/{user}/repos{?type,page,per_page,sort}", "user_search_url": "https://github.com/proxy/api.github.com/search/users?q={query}{&page,per_page,sort,order}" }What part(s) of the article would you like to see updated?
Either:
Add a page that covers
/authorizations.covering the bits about https://github.com/github/docs/blob/61b260231c18d4ad15f1663087c912025b48ac71/content/rest/overview/other-authentication-methods.md#using-the-oauth-authorizations-api-with-two-factor-authentication
Alternatively, there are scattered references to a deprecated (and removed from github.com) entrypoint
/authorizations. As it was removed in 2020 per https://github.com/proxy/developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/, it should not be referenced by current github.com (as opposed to GHES) documentation and shouldn't be referenced by api.github.com/meta (for the same reasons). -- This can presumably be done withIFmagic.Additional information
Apparently, my
PATisn't valid for this endpoint. As I get a 404 from it.