I've just submitted Gerrit change 153110[1] which will overhaul the token handling in the API, as described on the API Roadmap RFC.[2] The patch is not merged yet, feel free to join in the code review or reply with comments. Follow the Gerrit change for any changes to the information below. A followup to this announcement with deployment dates will be sent once the change is merged.

For clients, all the old methods of fetching tokens will continue to work with deprecation warnings. Usage levels of the deprecated methods on queries to WMF wikis will be evaluated once the MediaWiki 1.25 development cycle begins.

Changes visible to clients include:

* All tokens are available from the new meta=tokens query submodule.

** The "centralauth" token, which was provided by action=tokens but wasn't really a token in the sense of the rest, is now available from action=centralauthtoken.

** Note that it is possible to use meta=tokens along with other query prop, list, and meta modules.

* The help for all token parameters clearly indicates which type of token is needed.

* The output from action=paraminfo includes the token type as a property on the subobject describing the token parameter.

* All tokens may be cached as long as the session is valid; none are dependent on factors such as the page being edited or the user being targeted.

* Most token types have been replaced with a single 'csrf' token. This has long been the case in practice (e.g. see [3]), this just makes it official.

* The tokens returned for action=rollback and action=userrights (and certain extension modules) are no longer the same tokens used in the corresponding features in the web UI. The web UI tokens are accepted by the API for compatibility, but not vice versa.

* Any API query (with a few exceptions, mainly queries to the 'feed' modules) will return the current timestamp when passed the 'curtimestamp' parameter. This may be used to fetch the starttimestamp necessary for action=edit.

For extension authors, if your extension uses the core token handling it *will* need updating. I've already submitted patches for the 26 extensions hosted in WMF's Gerrit repository. The necessary changes are:

* needsToken() must return a string or false; true will result in an error. Unless there are special security issues that require a custom salt, 'csrf' should be returned.

** Since any truthy string is equivalent to the old behavior of returning boolean true, this will continue to work with older versions of MediaWiki.

* If a custom salt is needed, the new 'ApiQueryTokensRegisterTypes' hook must be used to register it.

* If web UI will be using a different salt (e.g. because it's included in links rather than posted form fields), a method getWebUITokenSalt() may be overridden to supply this salt for compatibility.

* It is no longer necessary to return data for 'token' from getAllowedParams() or getParamDescription(). Any return from getAllowedParams() will be overridden; a string from getParamDescription() will also be overridden with a standard message, while an array will have the standard message prepended.

** Compatibility with older versions of MediaWiki may be maintained by continuing to return data for 'token' from getAllowedParams() and a string for 'token' from getParamDescription().

* getTokenSalt() is no longer called or defined in ApiBase, and may be removed once compatibility with older versions of MediaWiki is no longer needed.

 [1]: https://gerrit.wikimedia.org/r/#/c/153110/
 [2]: https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap#Token_handling
 [3]: https://en.wikipedia.org/w/api.php?format=jsonfm&action=tokens&type=block|delete|edit|email|import|move|options|protect|unblock

--
Brad Jorsch (Anomie)
Software Engineer
Wikimedia Foundation