Skip to content

xToken lifecycle

What it is and is not

xtoken is a short-lived device-provisioning credential. It is not the user's VK OAuth token and not the long-lived Marusya session/session_secret pair.

The OAuth token is used only to create the Marusya session. The xToken is then created from that session and delivered to the speaker by sound. The audio therefore does not need to contain the VK access token.

Generation and delivery

  1. account/create_xtoken returns result.xtoken and optionally account_id.
  2. The app constructs ConnectRequest and serializes it as JSON.
  3. ADSSS encodes the JSON bytes into audio.
  4. The speaker decodes the audio, joins Wi-Fi, and contacts VK.
  5. account/info_xtoken reports the transition to CONNECTED.

A representative request structure is:

{
  "account_id": "redacted-account-id",
  "env": "prod",
  "wifi": {
    "cc": "RU",
    "psk": "redacted-wifi-password",
    "ssid": "redacted-ssid"
  },
  "xtoken": "redacted-short-lived-token"
}

Expiry and failure

TTL is enforced by VK's server, not by a constant in the Mini client. A used or expired xToken can return HTTP 400 during status checks. Generate a fresh one rather than replaying an old WAV indefinitely.

If setup fails, voice-agent::OnSetupFailed can call hwResetDevice for failure code 4. This explains why a bad/expired token can lead to a factory reset rather than a harmless retry.

Sensitive material

The WAV contains the Wi-Fi SSID/password and xToken. Treat it as a secret. Do not publish the WAV, stock-setup-request.json, session.json, or registration responses.