Extension:CentralAuth/API
Authentication
editCentralAuth has no login or signup API of its own (the standard clientlogin and signup APIs can be used for that, with the same parameters as MediaWiki core login), but it 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:
- When using the action API, via the
centralauthtoken
parameter. When making a POST CORS request to the action API, the parameter must be part of the preflight request and thus it must be in the URL, not the POST data. - When using the REST API, via a
Authorization: CentralAuthToken <token>
header.
You can use the mediawiki.ForeignApi ResourceLoader module to handle this for you.
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.
Returns a token that can be use to authenticate API requests on other wikis. For action API requests, put it in the centralauthtoken GET parameter. For REST API requests, add an Authorization: CentralAuthToken {token}
header. In MediaWiki frontend logic, you can use the mediawiki.ForeignApi
ResourceLoader module.
- Fetch a centralauthtoken
- api.php?action=centralauthtoken [open in sandbox]
User management
editThe 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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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
- aguexcludenamed
Exclude users of named accounts.
- Type: boolean (details)
- aguexcludetemp
Exclude users of temporary accounts.
- Type: boolean (details)
- 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: |
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, Temporary user 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=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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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, global-temporary-account-viewer, new-wikis-importer, oathauth-tester, ombuds, recursive-export, staff, steward, sysadmin, u4c-member, vrt-permissions, wmf-email-block-override, 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): AWB, convenient-discussions
- 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]
The following documentation is the output of Special: |
action=createlocalaccount
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: CentralAuth
- License: GPL-2.0-or-later
Forcibly create a local account. The central account must exist.
- username
User to create the local account for.
- This parameter is required.
- reason
Reason for creating the local account.
- token
A "csrf" token retrieved from action=query&meta=tokens
- This parameter is required.
- Forcibly create a local account for User:Example.
- api.php?action=createlocalaccount&username=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
Hide or lock (or unhide or unlock) a global user account.
- 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. This is used to detect edit conflicts. The value of hidden must be an empty string if not hidden or the strings
lists
orsuppressed
. The value of locked must be 1 for locked, 0 for unlocked. Examples: 2128506:LeeSmith::0; 3839611:VandalGoblin:suppressed:1.- 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: |
meta=globalrenamestatus (grs)
- This module requires read rights.
- Source: CentralAuth
- License: GPL-2.0-or-later
Show information about global renames that are in progress.
- grsuser
User that is being renamed. Can be either their old name or new name.
- Type: user, by any of username, IP, Temporary user, IP range and interwiki name (e.g. "prefix>ExampleName")
- Get information about the current global user
- api.php?action=query&meta=globalrenamestatus [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]
Group management
editThe 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: |
list=wikisets (ws)
- This module requires read rights.
- Source: CentralAuth
- License: GPL-2.0-or-later
Enumerate all wiki sets.
- wsfrom
The name of the wiki set to start from.
- wsprop
What pieces of information to include:
- type
- Opt-in based (includes only specified wikis) or opt-out based (includes all wikis except specified).
- wikisincluded
- The wikis that are included in this wiki set.
- wikisnotincluded
- The wikis that are not included in this wiki set.
- Values (separate with | or alternative): type, wikisincluded, wikisnotincluded
- wslimit
How many wiki sets to return.
- Type: integer or max
- The value must be between 1 and 500.
- Default: 10
- wsorderbyname
Order results by name.
- Type: boolean (details)
- List wiki sets
- api.php?action=query&list=wikisets [open in sandbox]
- Show wiki sets with types
- api.php?action=query&list=wikisets&wsprop=type&wslimit=200 [open in sandbox]