API:User group membership

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



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, or if they are already a member, update the expiry of their membership in that group.

Values (separate with | or alternative): bot, sysop, bureaucrat, steward, accountcreator, import, transwiki, ipblock-exempt, oversight, autopatrolled, translationadmin, confirmed, flow-bot, checkuser
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 bots).
Default: infinite
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.
tags

Change tags to apply to the entry in the user rights log.

Values (separate with | or alternative):
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]
Add user SometimeSysop to group sysop for 1 month.
api.php?action=userrights&user=SometimeSysop&add=sysop&expiry=1%20month&token=123ABC [open in sandbox]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:User_group_membership&oldid=2425795"