Extension:CentralAuth/API
Tokens[edit]
CentralAuth introduces three new tokens:
centralauthtoken
setglobalaccountstatus
deleteglobalaccount
centralauthtoken[edit]
CentralAuth allows your code to authenticate on the foreign wiki as the user currently logged in on the local wiki using a central authentication token (centralauthtoken
). Using those, one can make API calls to any wiki participating in the same single sign-on system, guaranteeing that the same associated account will be used for actions on both wikis even if the user is not logged in on the foreign wiki (doesn't have a session cookie for that domain).
First, acquire a token using action=centralauthtoken
request to the local wiki. A token is only valid for a single request, and will become invalid after 10 seconds.
Result |
---|
{
"centralauthtoken": {
"centralauthtoken": "138aa2df87605832076ac89c207f37ed1c3b01b"
}
}
|
Then, pass the token to any CORS request to the foreign wiki via the centralauthtoken
parameter. When making a POST CORS request, the parameter must be part of the preflight request and thus it must be in the URL, not the POST data. You can use the mediawiki.ForeignApi ResourceLoader module to handle this for you.
setglobalaccountstatus[edit]
The preferred method to obtain a setglobalaccountstatus token depends on the MediaWiki version:
- Versions 1.24 and later: action=query&meta=tokens
- Versions 1.20-1.23: action=tokens
deleteglobalaccount[edit]
The preferred method to obtain a deleteglobalaccount token depends on the MediaWiki version:
- Versions 1.24 and later: action=query&meta=tokens
- Versions 1.20-1.23: action=tokens
![]() | The following documentation is the output of Special: |
list=globalallusers (agu)
- This module requires read rights.
- Source: CentralAuth
- License: GPL-2.0-or-later
Enumerate all global users.
- agufrom
The username to start enumerating from.
- aguto
The username to stop enumerating at.
- aguprefix
Search for all users that begin with this value.
- agudir
Direction to sort in.
- One of the following values: ascending, descending
- Default: ascending
- agugroup
Limit users to given global groups.
- Values (separate with | or alternative): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, wmf-researcher
- aguexcludegroup
Exclude users in given global groups.
- Values (separate with | or alternative): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, wmf-researcher
- aguprop
What pieces of information to include:
- lockinfo
- Whether the user account is locked.
- groups
- Lists global groups that the user is in. This uses more server resources and may return fewer results than the limit.
- existslocally
- Adds the information if the user exists locally.
- Values (separate with | or alternative): existslocally, groups, lockinfo
- agulimit
How many total usernames to return.
- Type: integer or max
- The value must be between 1 and 500.
- Default: 10
- List global users
- api.php?action=query&list=globalallusers [open in sandbox]
- Show some information for global users starting from "ABC"
- api.php?action=query&list=globalallusers&agufrom=ABC&aguprop=lockinfo|groups|existslocally [open in sandbox]
![]() | The following documentation is the output of Special: |
list=globalgroups (ggp)
- This module requires read rights.
- Source: CentralAuth
- License: GPL-2.0-or-later
Enumerate all global groups.
- ggpprop
What pieces of information to include.
- Values (separate with | or alternative): rights
- List global groups
- api.php?action=query&list=globalgroups [open in sandbox]
- Show global groups with the rights they grant
- api.php?action=query&list=globalgroups&ggpprop=rights [open in sandbox]
![]() | The following documentation is the output of Special: |
meta=globaluserinfo (gui)
- This module requires read rights.
- Source: CentralAuth
- License: GPL-2.0-or-later
Show information about a global user.
- guiuser
User to get information about. If guiuser and guiid both are omitted, it defaults to the current user.
- Type: user, by any of username and interwiki name (e.g. "prefix>ExampleName")
- guiid
Global user ID to get information about. If guiuser and guiid both are omitted, it defaults to the current user.
- Type: integer
- guiprop
Which properties to get:
- groups
- Get a list of global groups this user belongs to.
- rights
- Get a list of global rights this user has.
- merged
- Get a list of merged accounts.
- unattached
- Get a list of unattached accounts.
- editcount
- Get the user's global edit count.
- Values (separate with | or alternative): editcount, groups, merged, rights, unattached
- Get information about the current global user
- api.php?action=query&meta=globaluserinfo [open in sandbox]
- Get information about global user Example
- api.php?action=query&meta=globaluserinfo&guiuser=Example&guiprop=groups|merged|unattached [open in sandbox]
![]() | The following documentation is the output of Special: |
action=centralauthtoken
- This module requires read rights.
- Source: CentralAuth
- License: GPL-2.0-or-later
Fetch a centralauthtoken for making an authenticated request to an attached wiki.
- Fetch a centralauthtoken
- api.php?action=centralauthtoken [open in sandbox]
![]() | The following documentation is the output of Special: |
action=deleteglobalaccount
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: CentralAuth
- License: GPL-2.0-or-later
Delete a global user.
- user
User to delete.
- This parameter is required.
- reason
Reason for deleting the user.
- token
A "deleteglobalaccount" token retrieved from action=query&meta=tokens
- This parameter is required.
- Delete the global account for User:Example
- api.php?action=deleteglobalaccount&user=Example&reason=Because+I+can [open in sandbox]
![]() | The following documentation is the output of Special: |
action=setglobalaccountstatus
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: CentralAuth
- License: GPL-2.0-or-later
Set a global user's status.
- user
User to change the status of.
- This parameter is required.
- locked
Change whether this user is locked or not.
- One of the following values: Can be empty, or lock, unlock
Change whether this user is not hidden, hidden from the global users list, or suppressed.
- One of the following values: Can be empty, or lists, suppressed
- reason
Reason for changing the user's status.
- statecheck
Optional MD5 of the expected current <userid>:<username>:<hidden>:<locked>, to detect edit conflicts. Set <locked> to 1 for locked, 0 for unlocked.
- token
A "setglobalaccountstatus" token retrieved from action=query&meta=tokens
- This parameter is required.
- Lock the global account for User:Example with reason "Spam"
- api.php?action=setglobalaccountstatus&user=Example&locked=lock&hidden=&reason=Spam [open in sandbox]
- Unlock and suppress the global account for User:Example with reason "I can"
- api.php?action=setglobalaccountstatus&user=Example&locked=unlock&hidden=suppressed&reason=I%20can [open in sandbox]
![]() | The following documentation is the output of Special: |
action=globaluserrights
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: CentralAuth
- License: GPL-2.0-or-later
Add/remove a user to/from global groups.
- user
Global username.
- Type: user, by any of username and user ID (e.g. "#12345")
- userid
- Deprecated.
Global user ID.
- Type: integer
- add
Add the user to these global groups.
- Values (separate with | or alternative): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, wmf-researcher
- expiry
Expiry timestamps. May be relative (e.g. 5 months or 2 weeks) or absolute (e.g. 2014-09-18T12:34:56Z). If only one timestamp is set, it will be used for all groups passed to the add parameter. Use infinite, indefinite, infinity, or never for a never-expiring user group.
- Separate values with | or alternative.
- Maximum number of values is 50 (500 for clients that are allowed higher limits).
- Default: infinite
- remove
Remove the user from these global groups.
- Values (separate with | or alternative): abusefilter-helper, abusefilter-maintainer, apihighlimits-requestor, captcha-exempt, founder, global-bot, global-deleter, global-flow-create, global-interface-editor, global-ipblock-exempt, global-rollbacker, global-sysop, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, vrt-permissions, wmf-researcher
- reason
Reason for the change.
- Default: (empty)
- token
A "userrights" token retrieved from action=query&meta=tokens
For compatibility, the token used in the web UI is also accepted.
- This parameter is required.
This parameter is currently unused.
- Values (separate with | or alternative): possible vandalism, repeating characters
- Add user FooBot to global group "bot", and remove from global groups "sysop" and "bureaucrat"
- api.php?action=userrights&user=FooBot&add=bot&remove=sysop|bureaucrat&token=123ABC [open in sandbox]
- Add the global user with ID 123 to global group "bot", and remove from global groups "sysop" and "bureaucrat"
- api.php?action=userrights&userid=123&add=bot&remove=sysop|bureaucrat&token=123ABC [open in sandbox]