API:Account creation

This page is part of the MediaWiki API documentation.

Language:	English

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • Etiquette and usage limits
• Tutorial
• Formats
• Error reporting
• Restricting usage
• Cross-site requests
• Authentication
  • Login
  • Logout
  • Account creation
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Expanding templates and rendering
• Purging pages' caches
• Parameter information
• Changing wiki content
  • Create and edit pages
  • Move pages
  • Rollback
  • Delete pages
  • Restore deleted revisions
  • (Un)protect pages
  • (Un)block users
  • (Un)watch pages
  • Send email
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
• Watchlist feed
• Wikidata
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code

MediaWiki version:

1.21

Creating accounts

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.

Parameters

• name: User name
• password: Password (ignored if mailpassword is set)
• domain: Domain for external authentication (optional)
• token: Account creation token obtained in first request
• email: Email address of user (Optional unless mailpassword is set)
• realname: Real name of user (Optional. Additionally many wikis have realname disabled via $wgHiddenPrefs)

  Note: To check whether realname is enabled or not, request api.php?action=query&meta=userinfo&uiprop=realname. If you get no realname property back in the response, realname is a hidden preference.

• mailpassword: If set to any value, a random password will be generated and e-mailed to the user (instead of using the password parameter)
• reason: Optional reason for creating the account. Will be shown in the account creation log (example).
• language: Language code to set as default for the user

Token

To create an account, a token is required. To retrieve a token, you make the request that you want, except with the token field being the empty string. Once you retrieve the token, you make the request again with the token filled in. This is similar to how the log in module works. See the example below for details.

Unlike most API Tokens, create account tokens will only work for one request. After creating an account with this module, you need a new token before you can create another account (The success message will contain such a token)

Example

Note: In this example, all parameters are passed in a GET request just for the sake of simplicity. However, action=createaccount requires POST requests; GET requests will cause an error.

Step 1: Retrieve token to create an account for GymBeauWhales

api.php?action=createaccount&name=GymBeauWhales&email=GymBeauWhales@wikipmediawiki.net&realname=Gymmy_Dahnyl_Wails&mailpassword=true&reason=Fun_and_profit&language=en&token=

We should now receive a response like:

<?xml version="1.0"?>
<api>
 <createaccount token="387bc54bd0ec29333178800ce4213306" result="needtoken" />
</api>

If you get an error about "newcookiesfornew", it is due to a bug in early versions of 1.21. Repeating the request should fix that

We take the token given here, and add it to the request:

Step 2: Actually create GymBeauWhales account

api.php?action=createaccount&name=GymBeauWhales&email=GymBeauWhales@wikipmediawiki.net&realname=Gymmy_Dahnyl_Wails&mailpassword=true&reason=Fun_and_profit&language=en&token=387bc54bd0ec29333178800ce4213306

Assuming everything works, we should get a result like:

<?xml version="1.0"?>
<api>
 <createaccount token="387bc54bd0ec29333178800ce4213306" userid="1234" username="GymBeauWhales" result="success" />
</api>

And GymBeauWhales@wikipmediawiki.net would get an email with instructions on how to log in.

Possible outputs

The result attribute can have one of three values:

• needtoken: A token is needed. A token parameter should also be set with a token to use.

  <?xml version="1.0"?><api><createaccount token="8217b293a6bd0bba84cc1cb661a06a5d" result="needtoken" /></api>
  

  • If you get a needtoken result when you are expecting a success result, make sure the token you are sending is correct, and that you are sending along any cookies sent by the API.
• success: Everything worked

  <?xml version="1.0"?><api><createaccount token="387bc54bd0ec29333178800ce4213306" userid="1234" username="foo" result="success" /></api>
  

• warning: Not used in core, however extensions can (in theory) add warnings, in which case the result attribute will be warning. However, this still generally means the account was created successfully.

Possible errors

All errors are formatted as:

<error code="code" info="info">

Many of the info codes to this module correspond to system messages. As a result the info part may change and in particular will vary with language.

• code: nocookiesfornew
  • info: The user account was not created, as we could not confirm its source. Ensure you have cookies enabled, reload this page and try again.
  • note: This code is sometimes returned due to a bug in early versions of MediaWiki 1.21. If you receive this error, retrying the request again (ensuring cookies are sent) should fix.
• code: sorbs_create_account_reason
  • info: Your IP address is listed as an open proxy in the DNSBL.
• code: noname
  • info: You have not specified a valid username
• code: userexists
  • info: Username entered already in use
• code: password-name-match
  • info: Your password must be different from your username.
• code: password-login-forbidden
  • info: The use of this username and password has been forbidden
• code: noemailtitle
  • info: No email address
• code: invalidemailaddress
  • info: The e-mail address cannot be accepted as it appears to have an invalid format
• code: externaldberror
  • info: There was either an authentication database error or you are not allowed to update your external account
• code: passwordtooshort
  • info: The password was shorter than the value of $wgMinimalPasswordLength
• code: noemail
  • info: There is no e-mail address recorded for user
• code: mustbeposted
  • info: The createaccount module requires a POST request
• code: acct_creation_throttle_hit
  • info: Visitors to this wiki using your IP address have created $1 accounts in the last day, which is the maximum allowed in this time period. As a result, visitors using this IP address cannot create any more accounts at the moment.
• code: wrongpassword
  • info: Incorrect password entered. Please try again.
  • note: Can be caused by the "domain" field being incorrect.
• code: aborted
  • aborted by an extension (info will have more details)
• code: blocked
  • info: You cannot create a new account because you are blocked
• code: permdenied-createaccount
  • info: You do not have the right to create a new account

Disable

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

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

See also

• How to restrict API usage
• Enable/Disable (write) API
• Extension:SignupAPI from 2011: in order to implement a Special:UserSignup form with an AJAX-y interactive validation, this extension also implements action=signup and action=validatesignup APIs.