register

register creates a server-local account, one that exists only on this server, and logs the connection in to it. It also joins the account to the server. To log in again later, use login.

Registration needs auth_mode set to cracked or cracked-only and cracked.allow_registration turned on. Check that handshake.val.capabilities contains register before you show a sign-up form.

Request

{
  "cmd": "register",
  "username": "alice",
  "password": "correct horse battery",
  "client": "mychat",
  "device": "computer"
}

Field	Type	Required	Description
username	string	Yes	2 to 32 characters: letters, digits, hyphens, and underscores. The server trims it and converts it to lowercase first.
password	string	Yes	4 to 72 characters.
bot	boolean	No	true creates a bot account. Defaults to false. It can’t be changed later.
client	string	No	Short name for your application. Same rules as auth.
device	string	No	Kind of device. Same rules as auth.
server_password	string	No	Server password, for servers in password access mode. handshake.val.access_control has the mode and whether a password is set (has_password).
invite_code	string	No	Invite code, for servers in invite access mode. Trimmed and converted to uppercase.

The new account’s public username is USR:local_<name>, for example USR:local_alice. Its nickname starts as the name you registered. Bot accounts get the same default roles as other accounts.

Response

Success sends auth_success, then ready with the new user and a local_upload_token. The frames are the same as for login.

Permissions

Anyone can send register, including before logging in. The server must allow registration and have room if limits.max_members is set.

Caution

The server saves the new account before it checks the access mode. If that check fails, you get auth_error, but the account already exists. Retry with login and the right server_password or invite_code, not with register.

Errors

Failures return auth_error. The server checks in this order and stops at the first failure.

val	When
Cracked authentication is disabled	The server’s auth_mode does not allow server-local accounts.
Registration is disabled	cracked.allow_registration is off.
Username and password required	username or password is missing, empty, or not a string.
Username must be 2-32 characters	The username is too short or too long.
Username can only contain letters, numbers, hyphens, and underscores	The username has another character.
Password must be 4-72 characters	The password is too short or too long.
bot must be a boolean	bot is present but is not true or false. null also fails.
This server is full	The server has reached limits.max_members.
Username already taken	An account with this name exists.
Unable to hash password	The server could not hash the password.
Unable to save user	The server could not save the account.

A failed access check returns auth_error with a reason and the server’s mode, plus application_id when an application is pending. The reasons are listed on the auth page and explained in access control.

See also

• login
• Server accounts