API:Login
 |
This page is part of the MediaWiki action API documentation. |
MediaWiki action API
- Introduction and quick start
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Searching (by title, content, coordinates...)
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
- Asserting
The MediaWiki API may require your application or client to provide authenticated user credentials to the API in order to complete an operation successfully. The standard way to become authenticated involves performing a login action request, constructing a cookie, and confirming the login by resubmitting the login action request with the confirmation token returned.
Contents
Whether to log in[edit | edit source]
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, it'll usually act with the credentials of the user who's running it. 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.
Application-specific user accounts[edit | edit source]
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.
Login gets several tokens that are needed by the server to recognize the logged-in user. In every call to api.php, the cookie set by this request must be passed. The cookies last for around a month and you should check that you need to log in based on detecting that you're not logged in (rather than logging once per session, for example). You can check this on any request using the assert generic parameter.
How to log in[edit | edit source]
Logging in through the API requires submitting a login query and constructing a cookie (many frameworks will construct the cookie automatically). In MediaWiki 1.15.3+, you must confirm the login by resubmitting the login request with the token returned.
Structure of login request[edit | edit source]
| Result |
|---|
{
"login": {
"result": "NeedToken",
"token": "b5780b6e2f27e20b450921d9461010b4",
"cookieprefix": "enwiki",
"sessionid": "17ab96bd8ffbe8ca58a78657a918558e"
}
}
|
The body of the POST can be empty. This request will also return a session cookie in the HTTP header (Set-Cookie: enwikiSession=17ab96bd8ffbe8ca58a78657a918558e; path=/; domain=.wikipedia.org; HttpOnly) that you have to return for the second request if your framework does not do this automatically. The sessionid parameter was added in MediaWiki 1.17 and later.
You might need to add the query parameter lgdomain, containing your domain name for authentication, if you're using an authentication plug-in like Extension:LDAP Authentication.
Confirm token[edit | edit source]
If the response to the above query was Success instead of NeedToken, you can skip this step. (This extra step was added in MediaWiki 1.15.3.) In MediaWiki 1.15.4, first phase of login in ApiLogin.php is broken, so login/sessionid parameter is not returned, thus token confirmation is impossible. Apply ApiLogin.php file from MediaWiki 1.15.5 to your installation as a quick workaround while you plan your upgrade to 1.15.5. ApiLogin.php from MediaWiki 1.16+ is incompatible with MediaWiki 1.15.3+.
Send a login request with POST, including the login as returned from previous request, and with the session cookie set in the header.
| Result |
|---|
{
"login": {
"result": "Success",
"lguserid": 12345,
"lgusername": "Bob",
"lgtoken": "b5780b6e2f27e20b450921d9461010b4",
"cookieprefix": "enwiki",
"sessionid": "17ab96bd8ffbe8ca58a78657a918558e"
}
}
|
Handle cookies[edit | edit source]
A successful action=login request will set cookies needed to be considered logged in. Many frameworks will handle these cookies automatically (such as the cookiejar in cURL). If so, by all means take advantage of this. If not, the most reliable method is to parse them from the HTTP response's Set-Cookie headers.
If this is not possible either, it is possible to construct the appropriate cookies from the various values returned by the action=login call, but this is not recommended as the necessary cookies may be changed without warning (e.g. something as simple as changing $wgSessionName would require changes to your manual cookie creation code).
When CentralAuth is enabled, as on Wikimedia wikis, the example above will not only log you in to a single domain, but also provide you with three centralauth cookies in the Set-Cookie response headers. To use these, duplicate those cookies (i.e. cookies whose names are prefixed with "centralauth_") and set the domain field of the new cookies to the new domain you'd like to log in at. Once this is done, any GET/POST request to this new domain will (assuming that the user has a SUL/global account) be answered with a reply containing Set-Cookie headers/Cookies specific to that domain.
Errors[edit | edit source]
Errors are returned in the result field. Possible values include:
| Result | Meaning |
|---|---|
| NoName | You didn't set the lgname parameter |
| Illegal | You provided an illegal username |
| NotExists | The username you provided doesn't exist |
| EmptyPass | You didn't set the lgpassword parameter or you left it empty |
| WrongPass | The password you provided is incorrect |
| WrongPluginPass | Same as WrongPass, returned when an authentication plugin rather than MediaWiki itself rejected the password |
| CreateBlocked | The wiki tried to automatically create a new account for you, but your IP address has been blocked from account creation |
| Throttled | You've logged in too many times in a short time. See also throttling |
| Blocked | User is blocked (only if $wgBlockDisablesLogin is set to true) |
| mustbeposted | The login module requires a POST request |
| NeedToken | Either you did not provide the login token or the sessionid cookie. Request again with the token and cookie given in this response |
Throttling[edit | edit source]
For security reasons, this module is throttled. By default, you get to login 5 times in 300 seconds, but this may vary from one wiki to another. When you exceed this limit, your login will fail (even if it's otherwise correct) with "result": "Throttled" and the number of seconds you need to wait in the wait field.
Examples[edit | edit source]
- Example login codes in PHP:
- Example login (requires Snoopy)
- Example login and navigate (using only file_get_contents)
- Example login (using cURL) - no Snoopy required
- Example login code in JS (using JQuery)
- Example login code in Python
|
The following documentation is the output of Special:ApiHelp/login, generated from login's source code. |
action=login (lg)
- 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.
- lgname
-
User name.
- lgpassword
-
Password.
- lgdomain
-
Domain (optional).
- lgtoken
-
Login token obtained in first request.
- Retrieve a login token.
- api.php?action=login&lgname=user&lgpassword=password
- Log in.
- api.php?action=login&lgname=user&lgpassword=password&lgtoken=123ABC
