API:Account creation

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page



MediaWiki action API

v · d · e
Createaccount
Create a new user account.
This module cannot be used as a GeneratorAPI:generator.
Prefix none
Required rights none
Post only? Yes
Generated help Current
Version added
≥ 1.21


You can create accounts using the API. This can be a new account for yourself, or you can create an account for someone else, with a random password mailed to that person. Account creations are recorded in Special:log/newusers. If you're logged in, your username will also be recorded when creating an account.

This page documents the account creation API as of MediaWiki 1.27. Documentation of the API as it existed in earlier versions is available here.

Creating an account[edit]

To create an account, a token is required. This token should be fetched using a tokensAPI:Tokens query.

This action implements an interactive account creation 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.

Simple example[edit]

On a wiki without any special authentication extensions, the fields needed might include username, password, and retype, and optionally email and realname.

Send an account creation request using POST (GET requests will cause an error).
api.php?action=createaccount&createreturnurl=http://example.com/&createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C&username=Bob&password=ExamplePassword&retype=ExamplePassword&email=bob%40example.com&realname=Robert%20Example [try in ApiSandbox]
Result 
{
    "createaccount": {
        "status": "PASS",
        "username": "Bob"
    }
}

Creating an account for someone else[edit]

If you're creating an account for someone else, you'll also need to specify a reason. You might also use mailpassword in place of password and retype to have MediaWiki send the new user a temporary password via email.

Send an account creation request using POST (GET requests will cause an error).
api.php?action=createaccount&createreturnurl=http://example.com/&createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C&username=Carl&mailpassword=1&email=carl%40example.com&realname=&reason=Carl%20asked%20me%20to. [try in ApiSandbox]
Result 
{
    "createaccount": {
        "status": "PASS",
        "username": "Carl"
    }
}

A complex example[edit]

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 account creation process process.

First step: answer the CAPTCHA and select OpenID authentication.
api.php?action=createaccount&createreturnurl=http://example.com/authenticating.php&createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C&captchaId=12345&captchaWord=MediaWikiIsCool&username=Alice&openIdProvider=openid.example.net&useOpenId=1 [try in ApiSandbox]
Result 
{
    "createaccount": {
        "status": "REDIRECT",
        "redirecttarget": "https://openid.example.net/openid-auth.php?scope=openid&response_type=code&client_id=ABC&redirect_uri=https://wiki.example.org/wiki/Special:OpenIDConnectReturn&state=XYZ123",
        "requests": [
            {
                "id": "OpenIdConnectResponseAuthenticationRequest",
                "metadata": {},
                "required": "required",
                "provider": "OpenID Connect at example.net",
                "account": "",
                "fields": {
                    "code": {
                        "type": "string",
                        "label": "OpenID Code",
                        "help": "OpenID Connect code response"
                    },
                    "state": {
                        "type": "string",
                        "label": "OpenID State",
                        "help": "OpenID Connect state response"
                    },
                }
            }
        ]
    }
}

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 createreturnurl 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.
api.php?action=createaccount&createcontinue=1&createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C&code=SplxlOBeZQQYbYS6WxSbIA&state=XYZ123 [try in ApiSandbox]
Result 
{
    "createaccount": {
        "status": "UI",
        "message": "Set up two-factor authentication",
        "requests": [
            {
                "id": "TwoFactorAuthenticationRequest",
                "metadata": {
                    "account": "Alice",
                    "secret": "6CO3 2AKV EP2X MIV5"
                },
                "required": "optional",
                "provider": "",
                "account": "",
                "fields": {
                    "2FAInfo": {
                        "type": "null",
                        "label": "A bunch of text describing how to set up two-factor auth.",
                        "help": "Two-factor authentication setup instructions"
                    },
                    "code": {
                        "type": "string",
                        "label": "Code",
                        "help": "Two-factor authentication code"
                    }
                }
            },
            {
                "id": "MediaWiki\\Auth\\ButtonAuthenticationRequest:skip2FASetup",
                "metadata": {},
                "required": "optional",
                "provider": "MediaWiki\\Auth\\ButtonAuthenticationRequest",
                "account": "MediaWiki\\Auth\\ButtonAuthenticationRequest:skip2FASetup",
                "fields": {
                    "skip2FASetup": {
                        "type": "button",
                        "label": "Skip",
                        "help": "Skip two-factor authentication setup"
                    }
                }
            }
        ]
    }
}

Now the client would prompt the user to set up a new account in their two-factor authentication app and enter the current code, or allow the user to skip 2FA setup. Let's assume the user does set up 2FA.

Third step: Set up two-factor authentication.
api.php?action=createaccount&createcontinue=1&createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C&code=817420 [try in ApiSandbox]
Result 
{
    "createaccount": {
        "status": "PASS",
        "username": "Alice"
    }
}

The account creation has finally succeeded.

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

Disable[edit]

To disable specifically this API feature, insert the following line in your configuration file:

$wgAPIModules['createaccount'] = 'ApiDisabled';

See also[edit]

action=createaccount (create)

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

Create a new user account.

The general procedure to use this module is:

  1. Fetch the fields available from action=query&meta=authmanagerinfo with amirequestsfor=create, and a createaccount token from action=query&meta=tokens.
  2. Present the fields to the user, and obtain their submission.
  3. Post to this module, supplying createreturnurl 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 createcontinue 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 createreturnurl. Then post to this module with createcontinue 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.
Parameters:
createrequests

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

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

Format to use for returning messages.

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

Merge field information for all authentication requests into one array.

Type: boolean (details)
createpreservestate

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

If action=query&meta=authmanagerinfo returned true for hasprimarypreservedstate, requests marked as primary-required should be omitted. If it returned a non-empty value for preservedusername, that username must be used for the username parameter.

Type: boolean (details)
createreturnurl

Return URL for third-party authentication flows, must be absolute. Either this or createcontinue 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 createcontinue request to this API module.

createcontinue

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

Type: boolean (details)
createtoken

A "createaccount" 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=create (or a previous response from this module, if applicable) to determine the requests available and the fields that they use.
Example:
Start the process of creating user Example with password ExamplePassword.
api.php?action=createaccount&username=Example&password=ExamplePassword&retype=ExamplePassword&createreturnurl=http://example.org/&createtoken=123ABC [open in sandbox]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Account_creation&oldid=2321398"