auth

auth logs the connection in with a Rotur account. It is one of three login commands, and the only one for Rotur accounts. For accounts stored on the server itself, use login or register.

Before you send auth

The server sends a handshake frame as soon as the socket opens. You need two things from it:

val.validator_key: a random key the server made for this connection. Ask Rotur to generate a validator for this key with the signed-in account, then send that validator in auth. The server checks the validator against the same key, so a validator made for one connection does not work on another.
val.capabilities: check that it contains auth. The server leaves auth out when its auth_mode is cracked-only, which means only server-local accounts are allowed.

See the protocol model for the full handshake.

Request

{
  "cmd": "auth",
  "validator": "<validator from Rotur>",
  "client": "mychat",
  "device": "computer"
}

Field	Type	Required	Description
`validator`	string	Yes	Rotur validator generated for `handshake.val.validator_key`. Must not be empty.
`client`	string	No	Short name for your application, such as `mychat`. See client names.
`device`	string	No	Kind of device running the connection, such as `computer` or `mobile`. See device names.
`server_password`	string	No	Server password. Needed when the server’s access mode is `password`.
`invite_code`	string	No	Invite code. Needed when the server’s access mode is `invite`. The server trims it and converts it to uppercase.

handshake.val.access_control tells you what the server needs before you log in. It has mode (open, whitelist, password, application, or invite) and has_password (whether a server password is set). In password mode, send server_password on every login unless the account is whitelisted. In invite mode, a valid code adds the account to the whitelist, so later logins don’t need it. See access control for how to join in each mode.

Client names

client names the application, not the user. It does not grant permissions or mark the account as a bot. Use the same value on every platform unless you want to tell builds apart, for example mychat-web and mychat-cli.

The server normalizes client and device the same way:

It trims whitespace and converts letters to lowercase.
The result must be 1 to 50 characters of ASCII letters, digits, dots, and hyphens.
Each dot-separated part must start and end with a letter or digit.

MyChat becomes mychat. my_chat, a..b, and https://chat.example are invalid. An invalid, missing, or non-string value is dropped. It never makes the login fail.

The connection reports no client name if you leave client out. Send it again after every reconnect.

Device names

Common values are computer, mobile, console, and terminal. The server turns desktop and laptop into computer.

If device is missing or invalid, the server guesses from the WebSocket User-Agent header. It recognizes consoles, phones and tablets, curl/wget/httpie, and desktop operating systems. If it can’t tell, no device is reported.

Other users see these names in user metadata.

Response

On success the server sends two frames, in this order:

{ "cmd": "auth_success", "val": "Authentication Successful" }

{
  "cmd": "ready",
  "user": {
    "username": "alice",
    "roles": ["user"],
    "color": null,
    "cracked": false,
    "clients": ["mychat"],
    "devices": ["computer"],
    "status": { "status": "online", "text": "" }
  }
}

ready.user is your own user object, with your current status. Some extra frames can follow:

users_list, when this connection was already logged in as a different account. It replaces the member list you had for the old account.
rate_limit, when the account is in a timeout. length is the time left in milliseconds.
ready.rotur_token is a boolean sent only to the server owner. It says whether the server has a Rotur token configured.

A first login also joins the account to the server. Other members then receive the join and presence events described in users and presence.

A failed auth never logs out an existing session on the connection.

Permissions

Anyone can send auth, including before logging in. The account must not be banned, must pass the server’s access mode, and the server must have room if limits.max_members is set.

Errors

Failures return auth_error instead of error:

{
  "cmd": "auth_error",
  "val": "Invalid invite code",
  "reason": "invite_invalid",
  "mode": "invite"
}

`val`	When
`Rotur authentication is disabled. Use login or register commands.`	The server’s `auth_mode` is `cracked-only`.
`Invalid authentication`	`validator` is missing or empty, a field has the wrong type, or Rotur rejects the validator.
`Authentication service unavailable`	The server could not reach Rotur.
`This Rotur account has been banned`	Rotur lists the account as banned. `reason` is `banned`.
`You have been banned from this server`	The account is banned on this server. `reason` is `banned`.
`This server is full`	The account is not a member yet and the server has reached `limits.max_members`.
`Unable to save user`	The server could not save the account.

Access-mode failures also include reason and mode:

`reason`	`val`
`password_required`	`This server requires a password to join`
`password_incorrect`	`Incorrect server password`
`not_whitelisted`	`You are not whitelisted on this server`
`application_required`	`This server requires approval to join. Submit an application first.`
`application_pending`	`Your join application is pending review`. The frame also has `application_id`.
`invite_required`	`This server requires an invite code to join`
`invite_invalid`	`Invalid invite code`
`invite_expired`	`This invite has expired`

In whitelist and application mode, existing members pass without extra fields. The server owner and whitelisted accounts pass every mode. To apply in application mode, send application_submit first. It is allowed before logging in. See access control for the full joining flow.