API:User group membership

From MediaWiki.org
Jump to navigation Jump to search

Other languages:
Deutsch • ‎English • ‎dansk • ‎français • ‎中文 • ‎日本語
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.

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, interface-admin, bureaucrat, steward, accountcreator, import, transwiki, ipblock-exempt, oversight, autopatrolled, checkuser, translationadmin, flow-bot, confirmed
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, interface-admin, bureaucrat, steward, accountcreator, import, transwiki, ipblock-exempt, oversight, autopatrolled, checkuser, translationadmin, flow-bot, confirmed
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]

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]

#!/usr/bin/python3

"""
    userrights.py
    MediaWiki Action API Code Samples
    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. For this login 
# method, Obtain credentials by first visiting
# https://test.wikipedia.org/wiki/Special:BotPasswords/
# See https://www.mediawiki.org/wiki/API:Login for more
# information on log in methods.
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)


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