API:Login

Login gets several tokens that are needed by the server to recognize 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).

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

Log in
This request will also return a session cookie in the HTTP header that you have to return for the second request if your framework does not do this automatically. The sessionid parameter was added in MedaWiki 1.17 and later. Note that you need to supply a parameter format=xml if MediaWiki returns HTML instead of XML.

You might need to add the query parameter, containing your domain name for authentication, if you're  using an authentication plug-in like Extension:LDAP Authentication.

Confirm token
If the response to the above query was  instead of , 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, even better to upgrade to 1.15.5. ApiLogin.php from MediaWiki 1.16+ is incompatible with MediaWiki 1.15.3+.

Construct cookies
A successful  request will set session cookies. Many frameworks will handle these cookies automatically (such as the cookiejar in cURL); if not, you will have to create them yourself.

If your wiki is not using the CentralAuth extension, you can construct them from the data returned as follows:


 * In the example above, you'd set the following cookie from the first request and send it for the second request:
 * enwiki_session =  (from the HTTP cookie  )
 * Additionally, you have to set after logged in sucessfully:
 * enwikiUserName =  (from the   field)
 * enwikiUserID =  (from the   field)
 * enwikiToken =  (from the   field)


 * Note that the  part is different for every wiki, and is returned in the   field.

When CentralAuth is enabled, as on Wikimedia wikis, the above method will only work on a single wiki. If you would like to use the advantages of Single-User-Login to be logged in on all wikis, the only usable option is to also parse the  headers manually and create additional cookies, instead of just accepting the cookies that it sets (which only sets them for the single wiki)

CentralAuth SUL Login
In the case of Wikimedia the cookie should be duplicated and added for following domains:
 * Login in as usual.
 * From the headers (especially from the second reponse) accept the cookies that it wants to set (typically there are 6 cookies being set. For example on Wikimedia Commons:  and   ). This part is usually covered by frameworks such as cURL with a cookiejar.
 * Now you have to parse the cookie by looking for the centralauth_ cookies and adding additional entries for all other wikis that centralauth covers in your setup.
 * .wikipedia.org
 * .meta.wikimedia.org
 * .wiktionary.org
 * .wikibooks.org
 * .wikiquote.org
 * .wikisource.org
 * .commons.wikimedia.org
 * .wikinews.org
 * .wikiversity.org
 * .mediawiki.org
 * .species.wikimedia.org

Errors
Errors are returned in the result field. Possible values are:
 * You didn't set the lgname parameter
 * You provided an illegal username
 * The username you provided doesn't exist
 * You didn't set the lgpassword parameter or you left it empty
 * The password you provided is incorrect
 * Same as, returned when an authentication plugin rather than MediaWiki itself rejected the password
 * The wiki tried to automatically create a new account for you, but your IP address has been blocked from account creation
 * You've logged in too many times in a short time. See also throttling
 * User is blocked
 * The login module requires a POST request
 * Either you did not provide the login token or the sessionid cookie. Request again with the  and cookie given in this response
 * Same as, returned when an authentication plugin rather than MediaWiki itself rejected the password
 * The wiki tried to automatically create a new account for you, but your IP address has been blocked from account creation
 * You've logged in too many times in a short time. See also throttling
 * User is blocked
 * The login module requires a POST request
 * Either you did not provide the login token or the sessionid cookie. Request again with the  and cookie given in this response
 * User is blocked
 * The login module requires a POST request
 * Either you did not provide the login token or the sessionid cookie. Request again with the  and cookie given in this response
 * Either you did not provide the login token or the sessionid cookie. Request again with the  and cookie given in this response
 * Either you did not provide the login token or the sessionid cookie. Request again with the  and cookie given in this response

Throttling
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  and the number of seconds you need to wait in the   field.

Examples

 * Example login code in PHP (requires Snoopy)
 * Example login code in PHP (using cURL) - no Snoopy required