From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:Login and the translation is 43% complete.

Other languages:
العربية • ‎български • ‎Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎Հայերեն • ‎italiano • ‎日本語 • ‎文言 • ‎polski • ‎русский • ‎sicilianu • ‎中文
このページは MediaWiki 操作 API の説明文書の一部です。

MediaWiki 操作 API

v · d · e

MediaWiki APIはある処理を上手く完了させる為に、認証されたユーザーに対してAPIを使用する資格情報を提供することを、あなたのアプリケーションやクライアントに要求する場合があります。 MediaWiki 1.27の時点では、認証に使用される2つのAPIアクション: loginclientloginがあります。

ボットやその他の非対話型アプリケーションは、認証が使用可能な場合はより安全度が高くなるので、一般に所有者限定のOAuth consumers を使用します。しかしボットのパスワード には、このページに記述されているようにlogin アクションを使用することが出来ます。

カスタムエディタやパトロール・アプリケーションのように、ウェブサイトを完全に置き換えることを意図しない対話型アプリケーションの場合は、ツールの認証に OAuthを使う事も出来ます。その方がより簡単で安全だからです。しかしそれが利用できない場合は clientlogin を使用することが出来ます。



あなたのクライアントを MediaWiki にログインさせる必要があるのは以下の場合でしょう:

  • 特定の権限を持つ利用者に制限された情報を取得したり、制限された操作を実行する必要がある
  • 膨大なリクエストを発行するため、リクエストごとの制限を緩和したアカウント以外での実行が現実的ではない場合

匿名で編集できるウィキでは、ログインしなくても API 経由で編集できますが、ログインすることを強く推奨します。 非公開のウィキでは、あらゆる API 機能についてログインが必須です。

あなたのクライアントがユーザーのウェブ・ブラウザで動く JavaScript で書かれている場合は、通常、そのクライアントを実行している利用者の認証情報を使用して動作しますので、クライアント自体のログインは不要でしょう。 この場合、ウェブ サービス API を使用してログインする必要はなく、利用者がウェブ インターフェイスを使用してログイン済みである必要があるのみです。

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.


アプリケーションをあなたのアカウントでログインさせるのでなく、アプリケーションで使用する利用者アカウントを別に作成した方がいい場合があります。 これは、アプリケーションが以下の場合に特に重要です:

  • 編集やその他の一括操作を自動的に実行する。
  • 巨大な、またはパフォーマンスに影響を与えるクエリを実行する。

別にアカウントを用意しておけば、アプリケーション経由で行った編集を簡単に見分けられますし、特殊な権限 (通常は「Bot」利用者グループ) をアプリケーションのアカウントに対して付与することもできます。 ウィキによっては、自動的な編集について方針を決めている場合、また「Bot」権限の付与申請について規定がある場合もあります。

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 userinfoAPI:Userinfo query module.


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.

login 操作

To successfully log in, a login token must first be retrieved. In MediaWiki 1.27 and later, this token should be fetched using a tokensAPI:Tokens query with type=login. 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.
  • Blocked (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.

clientlogin 操作

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 authmanagerinfoAPI: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-or-later

Log in and get authentication cookies.

This action should only be used in combination with Special:BotPasswords; use for main-account login is deprecated and may fail without warning. To safely log in to the main account, use action=clientlogin.


User name.




Domain (optional).


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

action=clientlogin (login)

(main | clientlogin)
  • This module only accepts POST requests.
  • Source: MediaWiki
  • License: GPL-2.0-or-later

Log in to the wiki using the interactive flow.

The general procedure to use this module is:

  1. Fetch the fields available from action=query&meta=authmanagerinfo with amirequestsfor=login, and a login token from action=query&meta=tokens.
  2. Present the fields to the user, and obtain their submission.
  3. Post to this module, supplying loginreturnurl and any relevant fields.
  4. Check the status in the response.
    • If you received PASS or FAIL, you're done. The operation either succeeded or it didn't.
    • If you received UI, present the new fields to the user and obtain their submission. Then post to this module with logincontinue and the relevant fields set, and repeat step 4.
    • If you received REDIRECT, direct the user to the redirecttarget and wait for the return to loginreturnurl. Then post to this module with logincontinue and any fields passed to the return URL, and repeat step 4.
    • If you received RESTART, that means the authentication worked but we don't have a linked user account. You might treat this as UI or as FAIL.

Only use these authentication requests, by the id returned from action=query&meta=authmanagerinfo with amirequestsfor=login or from a previous response from this module.

Separate values with | or alternative. Maximum number of values is 50 (500 for bots).

Format to use for returning messages.

One of the following values: html, wikitext, raw, none
Default: wikitext

Merge field information for all authentication requests into one array.

Type: boolean (details)

Preserve state from a previous failed login attempt, if possible.

Type: boolean (details)

Return URL for third-party authentication flows, must be absolute. Either this or logincontinue is required.

Upon receiving a REDIRECT response, you will typically open a browser or web view to the specified redirecttarget URL for a third-party authentication flow. When that completes, the third party will send the browser or web view to this URL. You should extract any query or POST parameters from the URL and pass them as a logincontinue request to this API module.


This request is a continuation after an earlier UI or REDIRECT response. Either this or loginreturnurl is required.

Type: boolean (details)

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

This parameter is required.
This module accepts additional parameters depending on the available authentication requests. Use action=query&meta=authmanagerinfo with amirequestsfor=login (or a previous response from this module, if applicable) to determine the requests available and the fields that they use.
Start the process of logging in to the wiki as user Example with password ExamplePassword.
api.php?action=clientlogin&username=Example&password=ExamplePassword&loginreturnurl=http://example.org/&logintoken=123ABC [open in sandbox]
Continue logging in after a UI response for two-factor auth, supplying an OATHToken of 987654.
api.php?action=clientlogin&logincontinue=1&OATHToken=987654&logintoken=123ABC [open in sandbox]