From MediaWiki.org
Jump to: navigation, search
Translate this page; This page contains changes which are not marked for translation.

Other languages:
Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎Հայերեն • ‎日本語 • ‎polski • ‎русский • ‎sicilianu • ‎中文
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page

MediaWiki action API

v · d · e

The MediaWiki API may require your application or client to provide authenticated user credentials to the API in order to complete an operation successfully. As of MediaWiki 1.27, there are two API actions used to authenticate: login and clientlogin.

Bots and other non-interactive applications should generally use owner-only OAuth consumers when available to authenticate as it is more secure, however bot passwords can be used with the login action as described on this page.

Interactive applications such as custom editors or patrolling applications that provide a service without intending to fully replace the website should generally also use OAuth for authenticating the tool, as it is easier and more secure, however the clientlogin action can be used if that is unavailable.

Interactive applications such as mobile apps that aim to completely replace access to the web-based user interface should use the clientlogin action to authenticate.

Whether to log in

Your client will need to log in to MediaWiki if:

  • it needs to obtain information or carry out an action that is restricted to users with certain rights
  • it is making large queries that would be inefficient without the higher per-request limits reserved for accounts with certain rights

On wikis that allow anonymous editing, it's possible to edit through the API without logging in, but it's highly recommended that you do log in. On private wikis, logging in is required to use any API functionality.

If your client is written in JavaScript running in the user's browser, it will usually act with the credentials of the user who's running it and so will not need to log in itself. In this case, you won't need to login using the web service API--you'll just need to ensure that the user has logged in through the web interface.

If your client is using OAuth or a similar mechanism, it will not need to explicitly log in as all OAuth requests are already authenticated.

Application-specific user accounts

Rather than having your application log in as yourself, you may want to create a separate user account just for your application. This is especially important if your application:

  • is carrying out automated editing or some other bulk operation.
  • invokes large or performance-intensive queries.

With a separate account, the changes made by your application can be easily tracked, and special rights (usually a "bot" user group) can be applied to the application's account. Some wikis have a policy related to automated editing, and/or a procedure for dealing with "bot" user group requests.

How to check if you're logged in

The login mechanism typically uses cookies to track the logged-in status of a session. Clients should check directly if they are logged in, rather than attempting to determine the status by examining the cookies or by blindly logging in whether or not it is required.

The recommended way to ensure that requests are logged in is to use the assert=user parameter accepted on all API calls. When this parameter is provided and the user is not logged in, an assertuserfailed error will be returned.

To directly check which user (if any) you are currently logged in as, use the userinfo query module.

How to log in

In MediaWiki versions before 1.27, only the login action is available and should be used by all clients needing to login. As of 1.27, the login action should only be used in combination with bot passwords, and clientlogin should be used by interactive applications.

Note that logging in and remaining logged in requires correct HTTP cookie handling by your client on all requests. Typically your framework or HTTP request library will handle this for you.

The login action

To successfully log in, a login token must first be retrieved. This token should be fetched using a tokens query in MediaWiki 1.27 and later. For older versions, a POST to the login action is required instead.

Fetching a token from action=login (deprecated since 1.27)

Other fields might be included in the response, however these are deprecated and should be ignored if present.

Once the token has been fetched, the login may proceed.

Send a login request with POST.

Other fields might be included in the response, however these are deprecated and should be ignored if present.

The result field in the output indicates whether the login was successful. Non-successful results include:

  • NeedToken if the lgtoken parameter was not provided or no session was active (e.g. your cookie handling is broken).
  • WrongToken if the supplied token was not a valid token.
  • Failed (since 1.27) if the login failed. A reason field will exist in the response containing and explanation of the failure.
  • Aborted (since 1.27) if the login using the main account password (rather than a bot password) cannot proceed because user interaction is required. The clientlogin action should be used instead.
  • NoName (before 1.27) if no lgname was provided.
  • Illegal (before 1.27) if the lgname is not a valid user name.
  • NotExists (before 1.27) if supplied user does not exist.
  • EmptyPass (before 1.27) if the supplied password is empty.
  • WrongPass or WrongPluginPass (before 1.27) if the password is incorrect.
  • CreateBlocked (before 1.27) if auto-creation of the account is required but is not possible.
  • Throttled (before 1.27) if login attempts from your IP have been throttled.
  • UserBlocked (before 1.27) if the user being logged in to is blocked and blocks prevent login on the wiki.
  • Aborted (before 1.27) if the login was aborted by an extension without further detail. A reason field may be present.

The clientlogin action

This action implements an interactive login process, which might include CAPTCHAs, interactions with third-party authentication services, two-factor authentication, and more. As such, the specific fields required may vary depending on the configuration of the wiki. A description of the fields needed should be fetched from the authmanagerinfo query.

On a wiki without any special authentication extensions, the fields needed might include username, password, and optionally rememberMe, so the login request would look something like this:

Send a client login request using POST (GET requests will cause an error).

On the other hand, a wiki with a CAPTCHA extension, an extension for authentication using OpenID Connect, and a two-factor authentication extension might have a more complicated authentication process.

First step: answer the CAPTCHA and select OpenID authentication.

The client would be expected to redirect the user's browser to the provided redirecttarget. The OpenID provider would authenticate, and redirect to Special:OpenIDConnectReturn on the wiki, which would validate the OpenID response and then redirect to the loginreturnurl provided in the first POST to the API with the code and state parameters added. The client gets control of the process back at this point and makes its next API request.

Second step: Back from OpenID.

Now the client needs to ask the user to check their two-factor authentication app for the current code, and submit that back to the server to continue the authentication process.

Third step: Two-factor authentication.

The authentication process has finally succeeded.

If at any point authentication fails, a response with status FAIL will be returned, along with a message to display to the user.

In certain cases it's possible to receive a RESTART response, for example if the OpenID Connect extension had no mapping for the OpenID account to any local user. In this case the client might restart the login process from the beginning or might switch to account creation, in either case passing the loginpreservestate or createpreservestate parameter to preserve some state.

action=login (lg)

(main | login)
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0+

Log in and get authentication cookies.

In the event of a successful log-in, the needed cookies will be included in the HTTP response headers. In the event of a failed log-in, further attempts may be throttled to limit automated password guessing attacks.


User name.




Domain (optional).


A "login" token retrieved from action=query&meta=tokens


(main | clientlogin)

This module has been disabled.