login

login logs the connection in to a server-local account, one created with register on this server. For a Rotur account, use auth.

Server-local accounts only exist when the server’s auth_mode is cracked or cracked-only. Check that handshake.val.capabilities contains login before you show a login form.

Request

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

Field	Type	Required	Description
username	string	Yes	The name you registered, such as alice. The server trims it and converts it to lowercase. Don’t send the public USR:local_alice form.
password	string	Yes	The account password. Must not be empty.
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.

Other users see a server-local account as USR:local_<name>, for example USR:local_alice. login never changes whether an account is a bot.

Response

Success sends auth_success, then ready, the same as auth. For server-local accounts, ready also carries local_upload_token:

{
  "cmd": "ready",
  "user": {
    "username": "USR:local_alice",
    "nickname": "alice",
    "roles": ["user"],
    "color": null,
    "cracked": true,
    "clients": ["mychat"],
    "devices": ["computer"],
    "pfp": "https://chat.example/avatar/USR%3Alocal_alice",
    "pfp_url": "https://chat.example/avatar/USR%3Alocal_alice",
    "status": { "status": "online", "text": "" }
  },
  "local_upload_token": "<token>"
}

Use local_upload_token to upload attachments and avatars over HTTP. It is valid only while this connection stays logged in. See server accounts.

Permissions

Anyone can send login, including before logging in. The account must not be banned and must pass the server’s access mode.

Errors

Failures return auth_error. A failed login never logs out an existing session on the connection.

val	When
Cracked authentication is disabled	The server’s auth_mode does not allow server-local accounts.
Username and password required	username or password is missing, empty, or not a string.
User not found	No server-local account has this name.
Invalid password	The password is wrong.
You have been banned from this server	The account is banned. reason is banned.
This server is full	The account left the server and the server has reached limits.max_members.
Unable to save user	The server could not save the login.

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

• register
• Server accounts