API:User group membership

This page is part of the MediaWiki API documentation.

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • Etiquette and usage limits
• Tutorial
• Formats
• Error reporting
• Restricting usage
• Cross-site requests
• Authentication
  • Login
  • Logout
  • Account creation
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Parsing wikitext and expanding templates
• Purging pages' caches
• Parameter information
• Changing wiki content
  • Create and edit pages
  • Move 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

Token

MediaWiki version:

1.16

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

api.php?action=query&list=users&ususers=Bob&ustoken=userrights

Adding users to and removing them from groups

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

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).

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

api.php?action=userrights&user=Bob&token=cf8df0403aeabf68099ac591daff42ad%2B\&add=sysop|bot&remove=bureaucrat&reason=Oops,%20put%20Bob%20in%20the%20wrong%20group

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

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.