Authentication

Player login, token refresh, and logout through the MusterBox SDK.

Authentication exchanges player credentials for a backend session. The SDK stores and rotates the tokens for you — your game never reads or verifies JWT signatures. The backend is the identity owner.

Login

use musterbox_session::contract::LoginRequest;

let request = LoginRequest::new("[e-mail]", "secret")
    .with_defaults(&auth_defaults); // device_id, device_name, device_os...

let success = sdk.authenticate(request)?;
// success.credentials, success.user, success.requires_otp

Browser:

await box.authenticate({
  identifier: "[e-mail]",
  password: "secret",
});

Under the hood this calls POST /api/v1/user/login and returns:

Field	Meaning
accessToken	Bearer access token used for subsequent calls
refreshToken	Rotated at /api/v1/auth/validate
expiresIn	Access-token lifetime in seconds
user	Backend user object
requiresOTP	When true, the SDK fails with AuthenticationFailed — OTP flows are not yet supported

Token lifetime

Token lifetime is derived from the backend expiresIn value and, when present, from JWT exp claims with clock-skew grace. The refresh-token fallback lifetime is 7 days when the backend omits expiry and the token is not a decodable JWT.

Refresh

The SDK refreshes automatically near expiry. Manual rotation:

let creds = sdk.refresh_session()?;

Logout

Revokes the server session (POST /api/v1/user/s/logout, body { "device_id": ... }) and clears local credentials.

sdk.logout()?;

Device metadata

Login requests can carry device context through [auth defaults]:

let mut defaults = AuthDefaults::default();
defaults.device_id = Some(device_id());
defaults.device_name = Some("Arcade Cabinet");
defaults.device_os = Some("macOS");
sdk.configure_auth_defaults(defaults);

device_id is also sent as the x-device-id header on login.

Security notes

Never log tokens, passwords, or PINs.

• Treat SessionNotAuthenticated as “re-authenticate” — never fall back to unauthenticated privileged calls.
• The SDK supports identifier+password credentials today; OTP-based verification is surfaced as an error until supported client-side.

Next: Sessions.