MediaWiki version:
1.12

POST request to block or unblock a user.

Blocking users

API documentation


Special:ApiHelp/block

Example

Making any POST request is a multi-step process:

  1. Log in, via one of the methods described on API:Login.
  2. GET a {{ll|Manual:Edit token|token}}. This token is equal to the edit token and changes at every login.
  3. Send a POST request, with the token, to block a user.

POST request

Example of blocking a user for 1 day, disabling account creation and email

Response

{
  "block": {
    "user": "Example",
    "userID": 2,
    "expiry": "2015-02-25T07:27:50Z",
    "id": "8",
    "reason": "Time out",
    "nocreate": "",
    "noemail": ""
  }
}

Sample code of blocking users

Python

#!/usr/bin/python3

"""
    block_user.py

    MediaWiki API Demos
    Demo of `Block` module: sending POST request to block user
    MIT license
"""

import requests

S = requests.Session()

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

# Step 1: GET request to fetch login token
PARAMS_0 = {
    "action": "query",
    "meta": "tokens",
    "type": "login",
    "format": "json"
}

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

LOGIN_TOKEN = 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
PARAMS_1 = {
    "action": "login",
    "lgname": "your_bot_username",
    "lgpassword": "your_bot_password",
    "lgtoken": LOGIN_TOKEN,
    "format": "json"
}

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

# Step 3: GET request to fetch CSRF token
PARAMS_2 = {
    "action": "query",
    "meta": "tokens",
    "format": "json"
}

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

CSRF_TOKEN = DATA['query']['tokens']['csrftoken']

# Step 4: POST request to block user
PARAMS_3 = {
    "action": "block",
    "user": "Example",
    "expiry": "2015-02-25T07:27:50Z",
    "reason": "Time out",
    "token": CSRF_TOKEN,
    "format": "json"
}

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

print(DATA)

PHP

<?php

/*
    block_user.php

    MediaWiki API Demos
    Demo of `Block` module: sending POST request to block user
    MIT license
*/

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

$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$csrf_Token = getCSRFToken(); // Step 3
block( $csrf_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" => "login",
		"lgname" => "bot_user_name",
		"lgpassword" => "bot_password",
		"lgtoken" => $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 CSRF token
function getCSRFToken() {
	global $endPoint;

	$params3 = [
		"action" => "query",
		"meta" => "tokens",
		"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"]["csrftoken"];
}

// Step 4: POST request to block user
function block( $csrftoken ) {
	global $endPoint;

	$params4 = [
		"action" => "block",
		"user" => "ABCD",
		"expiry" => "2020-02-25T07:27:50Z",
		"reason" => "API Test",
		"token" => $csrftoken,
		"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

/*  
    block_user.js
 
    MediaWiki API Demos
    Demo of `Block` module: sending POST request to block user

    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: "login",
        lgname: "bot_username",
        lgpassword: "bot_password",
        lgtoken: login_token,
        format: "json"
    };

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

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

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

// Step 4: POST request to block user
function block(csrf_token) {
    var params_3 = {
        action: "block",
        user: "ABCDEF",
        expiry: "2020-02-25T07:27:50Z",
        reason: "API Test",
        token: csrf_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

/*
	block_user.js

	MediaWiki API Demos
	Demo of `Block` module: sending POST request to block user

	MIT License
*/

var params = {
		action: 'block',
		user: 'ABCD',
		expiry: '2020-02-25T07:27:50Z',
		reason: 'API Test',
		format: 'json'
	},
	api = new mw.Api();

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

Unblocking users

API documentation


Special:ApiHelp/unblock

Example

POST request

Unblocking Example and apologizing

Response

{
  "id": "16",
  "user": "Example",
  "userid": 2,
  "reason": "Sorry Example"
}

Possible errors

Code ( Blocking) Info
alreadyblocked The user you tried to block was already blocked
cantblock You don't have permission to block users.
cantblock-email You don't have permission to block users from sending email through the wiki.
canthide You don't have permission to hide usernames from the block log.
This feature has to be enabled explicitly in LocalSettings.php.
invalidexpiry Invalid expiry time
invalidip Invalid IP address specified
invalidrange Invalid IP range
notoken The token parameter must be set.
nouser The user parameter must be set.
pastexpiry Expiry time "$1" is in the past.
permissiondenied You don't have permission to block users.
On most wikis, blocking users is restricted to sysops, but other wikis may have stricter rules.
rangedisabled Blocking IP ranges has been disabled
Code ( Unblocking) Info
notarget Either the id or the user parameter must be set
notoken The token parameter must be set.
idanduser The id and user parameters can't be used together
blockedasrange IP address "address" was blocked as part of range "range". You can't unblock the IP individually, but you can unblock the range as a whole.
cantunblock The block you specified was not found. It may have been unblocked already
permissiondenied You don't have permission to unblock users.
On most wikis, unblocking users is restricted to sysops, but other wikis may have different rules.

Parameter history

  • 1.29: Introduced tags
  • 1.21: Removed gettoken
  • 1.20: Deprecated gettoken
  • 1.18: Introduced watchuser
  • 1.14: Introduced allowusertalk, reblock

See also

  • API:User group membership - Add or remove users from a group
  • API:Blocks - Lists all blocks
This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.