Please clean up documentation for `/authorizations` #19279

jsoref · 2022-07-25T01:25:57Z

Code of Conduct

I have read and agree to the GitHub Docs project's 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 /meta docs -- https://docs.github.com/en/rest/meta#github-api-root

curl \
  -H "Accept: application/vnd.github+json" \ 
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/

Response

{
  "current_user_url": "https://api.github.com/user",
  "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}",
  "authorizations_url": "https://api.github.com/authorizations",
  "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",
  "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}",
  "emails_url": "https://api.github.com/user/emails",
  "emojis_url": "https://api.github.com/emojis",
  "events_url": "https://api.github.com/events",
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}",
  "issues_url": "https://api.github.com/issues",
  "keys_url": "https://api.github.com/user/keys",
  "label_search_url": "https://api.github.com/search/labels?q={query}&repository_id={repository_id}{&page,per_page}",
  "notifications_url": "https://api.github.com/notifications",
  "organization_url": "https://api.github.com/orgs/{org}",
  "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}",
  "organization_teams_url": "https://api.github.com/orgs/{org}/teams",
  "public_gists_url": "https://api.github.com/gists/public",
  "rate_limit_url": "https://api.github.com/rate_limit",
  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
  "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}",
  "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}",
  "starred_url": "https://api.github.com/user/starred{/owner}{/repo}",
  "starred_gists_url": "https://api.github.com/gists/starred",
  "topic_search_url": "https://api.github.com/search/topics?q={query}{&page,per_page}",
  "user_url": "https://api.github.com/users/{user}",
  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://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://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 with IF magic.

Additional information

Apparently, my PAT isn't valid for this endpoint. As I get a 404 from it.

The text was updated successfully, but these errors were encountered:

cmwilson21 · 2022-07-25T14:30:41Z

@jsoref Thanks so much for opening an issue and providing all this detail! I'll triage this for the team to take a look 👀

skedwards88 · 2022-07-26T18:06:03Z

@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?

jsoref · 2022-07-26T18:27:43Z

Does Basics of authentication cover what you are looking for?

No.

I'm really trying to figure out what permissions my GITHUB_TOKEN has. 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 methods as 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 docs page:
https://docs.github.com/en/rest/meta#github-api-root

the url is provided as a property of the response object for https://api.github.com/

{
...
  "authorizations_url": "https://api.github.com/authorizations",
...
}

To quote Google: "That’s all we know."

skedwards88 · 2022-07-26T22:10:41Z

Thanks for this additional detail.

The /authorizations endpoint is documented at https://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://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 about GITHUB_TOKEN to make that more discoverable.

Does this answer your questions?

jsoref · 2022-07-26T22:31:39Z

As you've noted that the /authorizations endpoint is gone, shouldn't the /meta endpoint on GitHub (and the docs for the same) not mention it (conditional on NOT GHES)?

Similarly, shouldn't the https://docs.github.com/en/rest/oauth-authorizations#list-your-authorizations page no longer list it, as opposed to

https://docs.github.com/en/enterprise-server@3.2/rest/oauth-authorizations#list-your-authorizations
...
https://docs.github.com/en/enterprise-server@3.6/rest/oauth-authorizations#list-your-authorizations

which can legitimately list it until they disappear...

jsoref · 2022-07-26T22:42:06Z

Filed #19323 for the GITHUB_TOKEN parts since apparently /authorizations is very much a ghost.

jsoref added the content label Jul 25, 2022

github-actions bot added the triage label Jul 25, 2022

cmwilson21 added waiting for review rest and removed triage labels Jul 25, 2022

jsoref changed the title ~~Please document /authorizations~~ Please clean up documentation for /authorizations Jul 26, 2022

Please clean up documentation for `/authorizations` #19279

Please clean up documentation for `/authorizations` #19279

jsoref commented Jul 25, 2022 •

edited

cmwilson21 commented Jul 25, 2022

skedwards88 commented Jul 26, 2022

jsoref commented Jul 26, 2022

skedwards88 commented Jul 26, 2022

jsoref commented Jul 26, 2022

jsoref commented Jul 26, 2022

Please clean up documentation for /authorizations #19279

Please clean up documentation for /authorizations #19279

Comments

jsoref commented Jul 25, 2022 • edited

Code of Conduct

What article on docs.github.com is affected?

What part(s) of the article would you like to see updated?

Additional information

cmwilson21 commented Jul 25, 2022

skedwards88 commented Jul 26, 2022

jsoref commented Jul 26, 2022

skedwards88 commented Jul 26, 2022

jsoref commented Jul 26, 2022

jsoref commented Jul 26, 2022

Please clean up documentation for `/authorizations` #19279

Please clean up documentation for `/authorizations` #19279

jsoref commented Jul 25, 2022 •

edited