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

As above, you can now create your tokens. Additionally, you have to set:


 * enwikiUserName =  (from the   field)
 * enwikiUserID =  (from the   field)
 * enwikiToken =  (from the   field)

Construct cookies
Many frameworks will handle cookies automatically; if not, you will need to create them yourself.

A successful action=login request will set the right cookies. If your wiki is not using the CentralAuth extension, you can also construct them from the data returned. In the example above, you'd set the following cookies: Note that the  part is different for every wiki, and is returned in the   field.
 * enwiki_session =  (from the   field)

When CentralAuth is enabled, as on Wikimedia wikis, the above method will not work. In that case, the only usable option is to parse the  headers in the HTTP response.

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
 * Request again with the  and cookies returned in the previous request
 * 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
 * Request again with the  and cookies returned in the previous request
 * User is blocked
 * The login module requires a POST request
 * Request again with the  and cookies returned in the previous request
 * Request again with the  and cookies returned in the previous request
 * Request again with the  and cookies returned in the previous request

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.