API:User group membership
Language: | English • Deutsch • 日本語 |
---|
![]() |
This page is part of the MediaWiki action API documentation. |
MediaWiki action API
- Introduction and quick start
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Searching (by title, content, coordinates...)
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Create and edit pages
- Move pages
- Merge pages
- Rollback
- Delete pages
- Restore deleted revisions
- (Un)protect pages
- (Un)block users
- (Un)watch pages
- Mark revisions of watched pages as visited
- Send email
- Patrol changes
- Import pages
- Change user group membership
- Upload files
- User options
- Tokens
- Page language
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
- Asserting
userrights | ||
---|---|---|
This module cannot be used as a Generator . |
||
Prefix | ||
Required rights | none | |
Post only? | Yes | |
Generated help | Current | |
Version added |
|
Contents
Token[edit]
A user rights token is required and can since MediaWiki 1.24 be obtained by action=query&meta=tokens&type=userrights.
For compatibility, the token used in the web UI is also accepted.
Previously, to change a user's group membership, the required token would depend on the name of the user whose rights were being changed. A user rights token could be obtained as follows: Obtaining a user rights token
Result |
---|
<?xml version="1.0"?>
<api>
<query>
<users>
<userid=2793024/>
<name="Bob"/>
</users>
<tokens>
<userrightstoken="f3c936c4ff8ee338a54e3a703ebafe3555aeb296+\\"/>
</tokens>
</query>
</api>
|
Adding users to and removing them from groups[edit]
Users can be added to groups or removed from them with action=userrights. Under normal circumstances, no specific rights are required to do this, but the user must have changeable groups available to them (see API:Userinfo). Blocked users require the userrights right, given only to bureaucrats by default.
Parameters[edit]
Only one of user or userid must be specified.
user
: The name of the user whose rights you want to change.userid
: The id of the user whose rights you want to change. 1.23+token
: A "userrights" token retrieved fromaction=query&meta=tokens
. Take care to urlencode the '+' as '%2B'.add
: A pipe-separated list of groups you want to add the user to. Groups you're not allowed to add and groups the user is already in will be silently ignoredremove
: A pipe-separated list of groups you want to remove the user from. Groups you're not allowed to remove and groups the users isn't in will be silently ignoredreason
: Reason for the change
Sample request[edit]
Note: In this example, all parameters are passed in a GET request just for the sake of simplicity. However, action=userrights requires POST requests; GET requests will cause an error.
Removing Bob from the bureaucrat group, and adding him to the sysop and bot groups
Result |
---|
<?xml version="1.0" encoding="utf-8"?>
<api>
<userrights user="Bob">
<removed>
<group>bureaucrat</group>
</removed>
<added>
<group>sysop</group>
<group>bot</group>
</add>
</userrights>
</api>
|
NOTE: If you don't have permission to add/remove users to/from groups, you'll get a result with empty <added />
and <removed />
tags rather than an error message, because all the groups you specified were silently ignored.
Possible errors[edit]
All errors are formatted as:
<error code="code" info="info">
Code | Info |
---|---|
nouser | The user parameter must be set |
nosuchuser | User "user" doesn't exist Note: This may happen when trying to change an anonymous user's rights. |
notoken | The token parameter must be set |
badtoken | Invalid token |
readonly | The wiki is in read-only mode Note: In read-only mode, absolutely nothing can be changed. |
![]() |
The following documentation is the output of Special:ApiHelp/userrights, generated from userrights's source code. |
action=userrights
- This module requires read rights.
- This module requires write rights.
- This module only accepts POST requests.
- Source: MediaWiki
- License: GPL-2.0+
Change a user's group membership.
- user
-
User name.
- Type: user name
- userid
-
User ID.
- Type: integer
- add
-
Add the user to these groups.
- Values (separate with | or alternative): bot, sysop, bureaucrat, steward, accountcreator, import, transwiki, ipblock-exempt, oversight, autopatrolled, translationadmin, confirmed, flow-bot, checkuser
- remove
-
Remove the user from these groups.
- Values (separate with | or alternative): bot, sysop, bureaucrat, steward, accountcreator, import, transwiki, ipblock-exempt, oversight, autopatrolled, translationadmin, confirmed, flow-bot, checkuser
- 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.
- Add user FooBot to group bot, and remove from groups sysop and bureaucrat.
- api.php?action=userrights&user=FooBot&add=bot&remove=sysop|bureaucrat&token=123ABC [open in sandbox]
- Add the user with ID 123 to group bot, and remove from groups sysop and bureaucrat.
- api.php?action=userrights&userid=123&add=bot&remove=sysop|bureaucrat&token=123ABC [open in sandbox]