Editing API:Account creation

{{TNT|API}}
{{TNT|API-head
|module=Createaccount
|description=Create a new user account.
|prefix=none
|rrights=none
|postonly=Yes
|version=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 [[/pre-1.27|here]].

== Creating an account ==
To create an account, a token is required. This token should be fetched using a {{ll|API:Tokens|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 {{ll|API:Authmanagerinfo|authmanagerinfo}} query.

=== Simple example ===

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

<div style="overflow:auto">{{TNT|ApiEx
|desc   = Send an account creation request using POST (GET requests will cause an error).
|p1     = action=createaccount
|p2     = createreturnurl=http://example.com/
|p3     = createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C
|p4     = username=Bob
|p5     = password=ExamplePassword
|p6     = retype=ExamplePassword
|p7     = email=bob%40example.com
|p8     = realname=Robert%20Example
|result = <source lang="javascript">
{
    "createaccount": {
        "status": "PASS",
        "username": "Bob"
    }
}</source>
}}

=== Creating an account for someone else ===

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

<div style="overflow:auto">{{TNT|ApiEx
|desc   = Send an account creation request using POST (GET requests will cause an error).
|p1     = action=createaccount
|p2     = createreturnurl=http://example.com/
|p3     = createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C
|p4     = username=Carl
|p5     = mailpassword=1
|p6     = email=carl%40example.com
|p7     = realname=
|p8     = reason=Carl%20asked%20me%20to.
|result = <source lang="javascript">
{
    "createaccount": {
        "status": "PASS",
        "username": "Carl"
    }
}</source>
}}

=== A complex example ===

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.

<div style="overflow:auto">{{TNT|ApiEx
|desc   = First step: answer the CAPTCHA and select OpenID authentication.
|p1     = action=createaccount
|p2     = createreturnurl=http://example.com/authenticating.php
|p3     = createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C
|p4     = captchaId=12345
|p5     = captchaWord=MediaWikiIsCool
|p6     = username=Alice
|p7     = openIdProvider=openid.example.net
|p8     = useOpenId=1
|result = <source lang="javascript">
{
    "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"
                    },
                }
            }
        ]
    }
}</source>
}}

The client would be expected to redirect the user's browser to the provided <samp>redirecttarget</samp>.

The OpenID provider would authenticate, and redirect to Special:OpenIDConnectReturn on the wiki, which would validate the OpenID response and then redirect to the <var>createreturnurl</var> provided in the first POST to the API with the <samp>code</samp> and <samp>state</samp> parameters added.

The client gets control of the process back at this point and makes its next API request.

<div style="overflow:auto">{{TNT|ApiEx
|desc   = Second step: Back from OpenID.
|p1     = action=createaccount
|p2     = createcontinue=1
|p3     = createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C
|p4     = code=SplxlOBeZQQYbYS6WxSbIA
|p5     = state=XYZ123
|result = <source lang="javascript">
{
    "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"
                    }
                }
            }
        ]
    }
}</source>
}}

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.

<div style="overflow:auto">{{TNT|ApiEx
|desc   = Third step: Set up two-factor authentication.
|p1     = action=createaccount
|p2     = createcontinue=1
|p3     = createtoken=29590a3037d325be70b93fb8258ed29257448cfb%2B%5C
|p4     = code=817420
|result = <source lang="javascript">
{
    "createaccount": {
        "status": "PASS",
        "username": "Alice"
    }
}</source>
}}

The account creation has finally succeeded.

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

== Disable ==
To disable specifically this API feature, insert the following line in your configuration file:
<source lang="php">
$wgAPIModules['createaccount'] = 'ApiDisabled';
</source>

== See also ==
* [[API:Restricting_API_usage|How to restrict API usage]]
* [[Manual:$wgEnableAPI|Enable/Disable (write) API]]
{{TNT|Api help|createaccount}}