Github Enhancement Suite website

The GitHub Enhancement Suite website features a page for extensions to use to acquire GitHub API tokens.

To engage with this page's API, you must have access to its page context's window. If your script includes @grant none in its metadata block, it will run in the page's context, and this will just be exposed to it as window; however, if the script uses @grant with any other value, it will need to also add @grant unsafeWindow, where the page's window context will be provided as unsafeWindow.

requestAuth(scopes,name,callback)

name can be an object with name and purpose properties, where purpose is an object with scopes as keys and descriptions of what those scopes are used for in your script. The name property is mandatory; the purpose property is optional.

All three of these properties will not be used in the same page load; when the page is loaded initially, the scopes list will be used (with name and purpose) to list the scopes that will be requested in authorization, and the callback will go unused. When the page is loaded in response to an authorization on GitHub, the scopes list will be ignored (as the user will already have been prompted with them), the callback function will be called with the token (including the scopes it grants), and acknowledge function, and the name will be used as the header for messages your script passes back via acknowledge.

callback(token,acknowledge)

This callback will be called with the resulting token from an authorization. Note that there is no guarantee that the given token will have all the scopes you requested attached: the user may opt to not grant the requested scopes to GitHub Enhancement Suite, in which case your script will need to acknowledge that the given token is insufficient accordingly.

The token is provided to all scripts that call requestAuth, regardless of whether or not it includes any or all of the scopes requested by the script, so that the script may choose how to handle a token based on which scopes are present; it may be enough for the script to use a given token, but with reduced functionality.

acknowledge is a function that takes a string that serves as a message representing the state of your extension in handling the token. It can be called as many times as necessary to update the progress of your extension's response to the given token (including a message of the token being ignored, if the given scopes were insufficient). Once your script has fully processed and stored the token, it should call acknowledge with the string OK.

Unlike the strings passed to requestToken, messages passed to acknowledge are interpreted and presented as HTML, so you will need to escape >, <, and & accordingly.

It is recommended that, after getting the token, your userscript should use it to request https://api.github.com/user and then save the token (via GM_setValue or whatever storage solution your script employs) in a key that pairs the token to (at least) the authorized user's login, as it's possible for a script to be used by different logged-in GitHub users who are not guaranteed to have separate storage contexts (eg. a user who logs out as themselves and logs in with the user account of a bot that they manage).