API:Edit - User group membership

From MediaWiki.org

This page is part of the MediaWiki API documentation.

Language:

English

[edit] Token

To change a user's group membership, a userrights token is required. This token is not equal to the edit token: it depends on the name of the user whose rights are being changed. A userrights token can be obtained as follows: Obtaining a userrights token

<?xml version="1.0"?>
<api>
  <query>
    <users>
      <user name="Bob" userrightstoken="6c291fe7b3336ebc912f21cfa076b3d9+\" />
    </users>
  </query>
</api>

[edit] Adding users to and removing them from groups

Users can be added to groups or removed from them with action=userrights.

[edit] Parameters

• user: The name of the user whose rights you want to change.
• token: The token obtained in the previous request. 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 (optional).

[edit] Sample request

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

<?xml version="1.0" encoding="utf-8"?>
<api>
  <changerights user="Bob" reason="Oops, put Bob in the wrong group">
    <add>
      <group>sysop</group>
      <group>bot</group>
    </add>
    <remove>
      <group>bureaucrat</group>
    </remove>
  </changerights>
</api>

NOTE: If you don't have permission to add/remove users to/from groups, you'll get a result with empty <add /> and <remove /> tags rather than an error message, because all the groups you specified were silently ignored.

[edit] Possible errors

All errors are formatted as:

<error code="code" info="info">

• code: nouser
  • info: The user parameter must be set
• code: nosuchuser
  • info: User ``user'' doesn't exist
    • This may happen when trying to change an anonymous user's rights.
• code: notoken
  • info: The token parameter must be set
• code: badtoken
  • info: Invalid token
• code: readonly
  • info: The wiki is in read-only mode
    • In read-only mode, absolutely nothing can be changed.