Please clean up documentation for `/authorizations`

[jsoref]

Code of Conduct

• [X] 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.

[cmwilson21]

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

[skedwards88]

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

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]

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]

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/[email protected]/rest/oauth-authorizations#list-your-authorizations ... https://docs.github.com/en/[email protected]/rest/oauth-authorizations#list-your-authorizations

which can legitimately list it until they disappear...

[jsoref]

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

[jsoref]

@skedwards88 ?

[jsoref]

@cmwilson21 ?

[jsoref]

@cmwilson21 ?

[myarb]

@jsoref Sorry for that! Reopening and keeping on our review board.

[skedwards88]

We've consolidated the REST API authentication info into a single article. We've also raised the issue of the /authorizations full removal with the team. It sounds like the root problem that you really want to identify is what permissions GITHUB_TOKEN has. 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.