Skip to content
OriginChats

Server account protocol

A server account is an account that one OriginChats server stores itself, with a username and password, instead of relying on Rotur. The protocol calls these accounts cracked, and that name is current, not legacy. This page collects the wire rules in one place. For a step-by-step walkthrough, read the client guide.

Discovery

Section titled “Discovery”

The handshake tells you whether server accounts are available:

auth_mode Accepted sign-in commands
rotur auth
cracked auth, login, and register when advertised
cracked-only login, and register when advertised

In the two cracked modes, capabilities includes login, local_attachment_auth_v1, and server_account_avatars_v1. It also includes register when the operator allows new accounts.

Older servers may leave out auth_mode. See legacy compatibility.

Usernames

Section titled “Usernames”

login and register take a bare name such as alice. The server trims and lowercases it, then adds a prefix to make the account’s protocol username:

alice  ->  USR:local_alice
  • Use the prefixed name in every other command and as the account’s key.
  • nickname holds the bare name for display.
  • Identify an account by server URL plus protocol username. Never merge a server account with a Rotur account because their names match.

The public user object has cracked: true for server accounts. It may also have bot: true, which is independent of being a server account. Passwords and password hashes never appear in any frame.

Sign-in result

Section titled “Sign-in result”

Success sends auth_success, then ready with the user and a local_upload_token:

{
  "cmd": "ready",
  "user": { "username": "USR:local_alice", "nickname": "alice", "cracked": true },
  "local_upload_token": "k3J9x2QvA7mB0cR5tY8wZ1nL4pH6sD9fG2jK5eU8iO1aV3bN7qW0xC4zM6yT2rE5"
}

Failures send auth_error. The client guide lists every val.

Upload token

Section titled “Upload token”

local_upload_token is a 64-character secret that lets HTTP requests act as the signed-in server account.

  • It belongs to one connection. Signing in again on the same socket replaces it, and closing the socket deletes it.
  • Send it in the request body, never in a URL. Keep it out of logs.
  • Attachment uploads, avatar uploads, and server image uploads accept it.
  • The server checks that the token maps to an existing, non-banned server account. Avatar uploads also require the token’s account to match the username in the path.

Rotur accounts never get this token. They authenticate HTTP requests with validator_key and a Rotur validator instead.

Avatars

Section titled “Avatars”

Server accounts have a server-hosted avatar at /avatar/{username}, returned in the user object as both pfp and pfp_url. Upload one with POST /avatar/{username} when the server advertises server_account_avatars_v1. HTTP routes documents both routes.

Signing

Section titled “Signing”

Server accounts have no Rotur signing key. The server ignores proof fields on their messages and edits, and doesn’t require them to sign slash calls. Check ready.user.cracked, not auth_mode, to know which kind of account is signed in. See signing.

See also

Section titled “See also”