Xity account identifiers and sign in
Current implementation 9 November 2026

Canonical wallet addresses remain unchanged, keep them as the stable key in signatures, balances, asset ownership, OAuth accounts and application records
A short Xity ID has an X prefix, eight random characters and a two character checksum, grouped for reading
An optional public account name has 4 to 24 lowercase ASCII letters, digits or underscores, starts with a letter and ends with a letter or digit
Old names remain permanently bound to the same account, an account can claim up to five names over its lifetime
Names are public identifiers, choosing a name does not verify a legal identity

GET /v1/accounts/resolve?identifier=value is public and accepts a name, @name, short Xity ID, canonical address or valid checksummed address
GET /account returns the signed in account descriptor with address, short_id, name and revision
PUT /account/name requires a root session, name, expected revision, timestamp and current wallet signature
The signed object is domain xity.account.name.v1 plus address, chain_id, genesis_hash, name, revision and timestamp
Canonical JSON and Ed25519 rules are the same as the existing account configuration signing helper
Do not truncate addresses or put short IDs into transaction signatures
The SDK method resolveAccount returns the canonical address to use before preparing a transfer
OAuth userinfo includes address, short_id and account_name, the address remains the stable account key

A personal QR is XITY:ACCOUNT:1: followed by a 43 character opaque locator
GET /account/qr requires a root session and returns value, revision and account
POST /auth/qr/resolve accepts value and returns only the public account descriptor
POST /account/qr/replace requires a root session, current QR revision, timestamp and wallet signature
Its signing domain is xity.account.qr.v1, signed fields are address, chain_id, genesis_hash, revision and timestamp
A successful replacement invalidates the old locator in the same SQLite transaction
A personal QR only selects an account, the account password is still required
An ordinary QR scanner can decode the pattern, the payload contains no password, signing key or bearer session

POST /auth/device/start explicitly creates a computer connection request and returns request_id, poll_secret, qr, user_code, match_code, expires_at and interval
The QR is XITY:DEVICE:1: followed by a 43 character opaque locator
Keep poll_secret only in the requesting browser memory, never put it in a QR, URL, log or persistent browser storage
A signed in device reads the QR with the local camera or imports its PNG, JPEG or WebP image
The manual user_code works when neither device has a camera
POST /auth/device/lookup requires a root session and accepts code, either the QR payload or manual code
Show match_code on both devices and ask the person to confirm they started this request on their own computer
POST /auth/device/decide requires request_id, approve or decline, timestamp and wallet signature
Its signing domain is xity.account.device.v1, signed fields are address, chain_id, genesis_hash, request_id, challenge, decision and timestamp
Approval requires a current configured portable account password
POST /auth/device/poll accepts request_id and poll_secret, poll no faster than the returned interval
A request expires after five minutes, approval returns a public account descriptor and never a session, signing key or encrypted key bundle
The computer then uses the ordinary account password, portable vault and fresh wallet challenge flow
Recovery or wallet freezing invalidates an existing device approval

Camera access begins only after Use camera is pressed, camera and photo decoding stay on the device
Only the two explicit Xity QR payload formats are accepted, a scanned URL is never followed as an arbitrary navigation instruction
Personal QR replacement and account name edits require a fresh signature, possession of a session alone cannot approve them
Separate sign ins receive independent single use challenges
Key proof and session key binding share the chain rotation lock, recovery cannot rebind an old key proof to the new key
Password configuration derives its verifier outside the chain lock and rechecks the session, current key and expected revision before committing
Existing portable password, saved device key, offline transfer, prepared recovery and OAuth return paths remain available

Existing device compatibility updated 9 November 2026

An existing saved key keeps its original device PIN when account password sign in stores another encrypted copy
The portable copy is separate, both copies remain encrypted, no PIN or password is sent to Xity
A transfer code is exported from the copy unlocked by the entered PIN or password
Recovery and explicit import remain authoritative, a stale sign in cannot overwrite a different replacement key or recreate a removed key
An account without portable password enrollment can still sign in using its original saved device key and PIN
Saved device keys belong to the browser and exact website origin, account password access becomes portable after it is enabled in Security
If the previous client already replaced a device PIN, the account password used for that sign in unlocks that copy, the original PIN cannot be reconstructed automatically