Connection Sequence

Prechecks

Desktop: LokiPublicChatFactoryAPI::validServer https://github.com/loki-project/session-desktop/blob/clearnet/js/modules/loki_public_chat_api.js

This makes sure the server:

• is online
• has a valid SSL certificate (unless it's a .loki TLD)

Get a valid token

Desktop: LokiPublicChatFactoryAPI::findOrCreateServer => LokiAppDotNetServerAPI::getOrRefreshServerToken https://github.com/loki-project/session-desktop/blob/clearnet/js/modules/loki_app_dot_net_api.js

Try to get a valid token, if you fail to get a token, then likely not on the whitelist or you have been blacklisted (or so other failure or bug).

get token

desktop: LokiAppDotNetServerAPI::requestToken

server: getChallengeHandler https://github.com/loki-project/session-open-group-server/blob/master/dialects/token/dialect_tokens_handlers.js

GET /loki/v1/get_challenge?pubKey=PUBKEY

returns an encrypted string (libloki.crypto.decryptToken) with your token

• 422 is no pubkey
• 401 if pubkey isn't whitelisted and whitelist is active
• 500 if error getting challenge (internal communication failure)

submit challenge

desktop: LokiAppDotNetServerAPI::submitToken

server: submitChallengeHandler https://github.com/loki-project/session-open-group-server/blob/master/dialects/token/dialect_tokens_handlers.js

POST /loki/v1/submit_challenge

headers: Content-Type: application/json

body: JSON encoded:

{
  pubKey: PUBKEY,
  token: DECODED_TOKEN
}

This marks the gotten token as active (otherwise the token is inert) returns

• 200 on success
• 422 is no pubkey or no token
• 401 is not whitelisted or invalid (expired)
• 500 if can't confirm or non-invalid error

verify token works

LokiAppDotNetServerAPI::getOrRefreshServerToken

token spec: http://206.81.100.146:3000/reference/resources/token/

GET /token?access_token=DECODED_TOKEN

alternative you can pass access_token via Authorization header prefixed with a Bearer

401 means token is not valid and a new one should be fetched (this can happen if the DB gets wiped) otherwise expect a 200 with a JSON object

Normal usage

if any request returns any 4xx code, this likely means your token is invalid and you need a new token. on Desktop, if we get a 401, we immediately request a token (refresh)