API:Account creation
This page is part of the MediaWiki action API documentation. |
MediaWiki action API
- Introduction and quick start
- FAQ
- Tutorial
- Formats
- Error reporting
- Restricting usage
- Cross-site requests
- Authentication
- Queries
- Searching (by title, content, coordinates...)
- Parsing wikitext and expanding templates
- Purging pages' caches
- Parameter information
- Changing wiki content
- Create and edit pages
- Move pages
- Merge pages
- Rollback
- Delete pages
- Restore deleted revisions
- (Un)protect pages
- (Un)block users
- (Un)watch pages
- Mark revisions of watched pages as visited
- Send email
- Patrol changes
- Import pages
- Change user group membership
- Upload files
- User options
- Tokens
- Page language
- Watchlist feed
- Wikidata
- Extensions
- Using the API in MediaWiki and extensions
- Miscellaneous
- Implementation
- Client code
- Asserting
Createaccount | ||
---|---|---|
Create a new user account. This module cannot be used as a Generator . |
||
Prefix | none | |
Required rights | none | |
Post only? | Yes | |
Generated help | Current | |
Version added |
|
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.
Contents
Creating an account[edit]
To create an account, a token is required. This token should be fetched using a 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 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.
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.
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.
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.
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.
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]
The following documentation is the output of Special:ApiHelp/createaccount, generated from createaccount's source code. |
action=createaccount (create)
- 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:
- Fetch the fields available from action=query&meta=authmanagerinfo with amirequestsfor=create, and a createaccount token from action=query&meta=tokens.
- Present the fields to the user, and obtain their submission.
- Post to this module, supplying createreturnurl and any relevant fields.
- 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.
- 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.
- 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]