API:User group membership

From MediaWiki.org
Jump to: navigation, search
Language: English  • Deutsch • 日本語
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page



MediaWiki action API

v · d · e
userrights

This module cannot be used as a GeneratorAPI:generator.
Prefix
Required rights none
Post only? Yes
Generated help Current
Version added
≥ 1.16

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

api.php?action=query&list=users&meta=tokens&ususers=Bob&type=userrights [try in ApiSandbox]
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 from action=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 ignored
  • remove: 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 ignored
  • reason: 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

api.php?action=userrights&user=Bob&token=cf8df0403aeabf68099ac591daff42ad%2B\&add=sysop|bot&remove=bureaucrat&reason=Oops,%20put%20Bob%20in%20the%20wrong%20group [try in ApiSandbox]
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.

action=userrights

(main | 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.

Parameters:
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.
Examples:
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]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:User_group_membership&oldid=2318701"