API:User group membership

From mediawiki.org
MediaWiki version:
1.16

POST request to add or remove users from a group, thereby granting or removing certain user rights.

API documentation[edit]


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-or-later

Change a user's group membership.

Specific parameters:
Other general parameters are available.
user

User.

Type: user, by any of username and user ID (e.g. "#12345")
userid
Deprecated.

Specify user=#ID instead.

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): accountcreator, autopatrolled, bot, bureaucrat, checkuser, confirmed, flow-bot, import, interface-admin, ipblock-exempt, no-ipinfo, push-subscription-manager, steward, suppress, sysop, translationadmin, transwiki, uploader
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 clients that are allowed higher limits).
Default: infinite
remove

Remove the user from these groups.

Values (separate with | or alternative): accountcreator, autopatrolled, bot, bureaucrat, checkuser, confirmed, flow-bot, import, interface-admin, ipblock-exempt, no-ipinfo, push-subscription-manager, steward, suppress, sysop, translationadmin, transwiki, uploader
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): convenient-discussions, possible vandalism, repeating characters
watchuser

Watch the user's user and talk pages.

Type: boolean (details)
watchlistexpiry

Watchlist expiry timestamp. Omit this parameter entirely to leave the current expiry unchanged.

Type: expiry (details)
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]

Example[edit]

To use this API, you first need to log in to verify your own user group membership. Only certain groups are granted the ability to alter user rights via this API. See API:Login for more details on logging in.

Once you are logged in, make a GET request to obtain a userrights token .


The query above applies to MediaWiki v1.24+; in older versions, the userrights token would depend on the name of the user whose rights were being changed. The query would be made like so:



For compatibility reasons, the API will also accept the token used in the web UI.

Whichever method you choose, once you have your token, you can use it to make your userrights request, as seen below.

POST request[edit]

Remove Bob from the bureaucrat group, and add them to the sysop group, thereby granting them sysop rights.


Response[edit]

{
    "userrights": {
        "user": "Bob",
        "userid": 2793024,
        "removed": ["bureaucrat"],
        "added": ["sysop"]
    }
}

Sample code[edit]

Python[edit]

#!/usr/bin/python3

"""
    userrights.py

    MediaWiki API Demos
    Demo of `Userrights` module: Add and remove user rights by
    changing the user's group membership.
    MIT license
"""

import requests

S = requests.Session()

URL = "https://test.wikipedia.org/w/api.php"

# Step 1: Retrieve a login token
PARAMS_1 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"
}

R = S.get(url=URL, params=PARAMS_1)
DATA = R.json()

LOGIN_TOKEN = DATA["query"]["tokens"]["logintoken"]

# Step 2: Send a post request to log in. See
# https://www.mediawiki.org/wiki/Manual:Bot_passwords
# for a special note on logging in using a simplified
# interface when accessing wikis via an application,
# rather than the GUI
PARAMS_2 = {
    "action": "login",
    "lgname": "username",
    "lgpassword": "password",
    "lgtoken": LOGIN_TOKEN,
    "format": "json"
}

R = S.post(URL, data=PARAMS_2)

# Step 3: Obtain a Userrights token
PARAMS_3 = {
    "action": "query",
    "format": "json",
    "meta": "tokens",
    "type": "userrights"
}

R = S.get(url=URL, params=PARAMS_3)
DATA = R.json()

USERRIGHTS_TOKEN = DATA["query"]["tokens"]["userrightstoken"]

# Step 4: Request to add or remove a user from a group
PARAMS_4 = {
    "action": "userrights",
    "format": "json",
    "user": "Bob",
    "add": "sysop",
    "remove": "bureaucrat",
    "reason": "OOPS! added Bob to the wrong group",
    "token": USERRIGHTS_TOKEN
}

R = S.post(URL, data=PARAMS_4)
DATA = R.json()

print(DATA)

PHP[edit]

<?php

/*
    userrights.php

    MediaWiki API Demos
    Demo of `Userrights` module: Add and remove user rights by
	changing the user's group membership.

    MIT license
*/

$endPoint = "http://dev.wiki.local.wmftest.net:8080/w/api.php";

$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$userrights_Token = getUserRightsToken(); // Step 3
change_userrights( $userrights_Token ); // Step 4

// Step 1: GET request to fetch login token
function getLoginToken() {
	global $endPoint;

	$params1 = [
		"action" => "query",
		"meta" => "tokens",
		"type" => "login",
		"format" => "json"
	];

	$url = $endPoint . "?" . http_build_query( $params1 );

	$ch = curl_init( $url );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	$result = json_decode( $output, true );
	return $result["query"]["tokens"]["logintoken"];
}

// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
	global $endPoint;

	$params2 = [
		"action" => "clientlogin",
		"username" => "username",
		"password" => "password",
		'loginreturnurl' => 'http://127.0.0.1:5000/',
		"logintoken" => $logintoken,
		"format" => "json"
	];

	$ch = curl_init();

	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

}

// Step 3: GET request to fetch userrights token
function getUserRightsToken() {
	global $endPoint;

	$params3 = [
		"action" => "query",
		"meta" => "tokens",
		"type" => "userrights",
		"format" => "json"
	];

	$url = $endPoint . "?" . http_build_query( $params3 );

	$ch = curl_init( $url );

	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	$result = json_decode( $output, true );
	return $result["query"]["tokens"]["userrightstoken"];
}

// Step 4: POST request to add or remove a user from a group
function change_userrights( $userrightstoken ) {
	global $endPoint;

	$params4 = [
		"action" => "userrights",
		"user" => "ABCDEF",
		"add" => "bot",
		"expiry" => "infinite",
		"reason" => "API Testing",
		"token" => $userrightstoken,
		"format" => "json"
	];

	$ch = curl_init();

	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params4 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );

	$output = curl_exec( $ch );
	curl_close( $ch );

	echo ( $output );
}

JavaScript[edit]

/*  
    userrights.js
 
    MediaWiki API Demos
    Demo of `Userrights` module: Add and remove user rights by
	changing the user's group membership.

    MIT license
*/

var request = require('request').defaults({jar: true}),
    url = "http://dev.wiki.local.wmftest.net:8080/w/api.php";

// Step 1: GET request to fetch login token
function getLoginToken() {
    var params_0 = {
        action: "query",
        meta: "tokens",
        type: "login",
        format: "json"
    };

    request.get({ url: url, qs: params_0 }, function (error, res, body) {
        if (error) {
            return;
        }
        var data = JSON.parse(body);
        loginRequest(data.query.tokens.logintoken);
    });
}

// Step 2: POST request to log in. 
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest(login_token) {
    var params_1 = {
        action: "clientlogin",
        username: "username",
        password: "password",
        loginreturnurl: "http://127.0.0.1:5000/",
        logintoken: login_token,
        format: "json"
    };

    request.post({ url: url, form: params_1 }, function (error, res, body) {
        if (error) {
            return;
        }
        getUserRightsToken();
    });
}

// Step 3: GET request to fetch UserRights token
function getUserRightsToken() {
    var params_2 = {
        action: "query",
        meta: "tokens",
        type: "userrights",
        format: "json"
    };

    request.get({ url: url, qs: params_2 }, function(error, res, body) {
        if (error) {
            return;
        }
        var data = JSON.parse(body);
        userrights(data.query.tokens.userrightstoken);
    });
}

// Step 4: POST request to add or remove a user from a group
function userrights(userrights_token) {
    var params_3 = {
        action: "userrights",
        user: "ABCDEFG",
        add: "bot",
        expiry: "infinite",
        reason: "API Testing",
        token: userrights_token,
        format: "json"
    };

    request.post({ url: url, form: params_3 }, function (error, res, body) {
        if (error) {
            return;
        }
        console.log(body);
    });
}

// Start From Step 1
getLoginToken();

MediaWiki JS[edit]

/*
	userrights.js

	MediaWiki API Demos
	Demo of `Userrights` module: Add and remove user rights by
    changing the user's group membership.

	MIT License
*/

var params = {
		action: 'userrights',
		user: 'ABCD',
		add: 'sysop',
		reason: 'Added ABCD to the sysop group',
		format: 'json'
	},
	api = new mw.Api();

api.postWithToken( 'userrights', params ).done( function ( data ) {
	console.log( data );
} );

Possible errors[edit]

Code Info
nouser The user parameter must be set.
nosuchuser User "user" doesn't exist
This may happen when trying to change an anonymous user's rights.
notoken The token parameter must be set.
badtoken Invalid CSRF token.
readonly The wiki is currently in read-only mode.

Parameter history[edit]

  • v1.29: Introduced expiry
  • v1.23: Introduced userid

Additional notes[edit]

  • By default, only users in the bureaucrat group can grant or remove user rights.
  • Some wikis allow non-bureaucrats to grant or remove rights on a limited basis, such as restricting those abilities to the user's own account.
  • If you do not possess the ability to grant or remove rights to the target user, the API will not throw an error; instead, the add and remove fields in the response will simply contain empty arrays.

See also[edit]

  • Help:User rights and groups - describes how user rights and group membership work in greater detail.
  • Special:ListGroupRights - lists all the rights and privileges conferred to each user group on a particular wiki.
  • Special:UserRights - a GUI way to add or remove user rights, available in wikis running v1.29+.
  • API:Users - gets information about a list of users, including their groups and rights.