WorkoutKit

Appearance

SDK Authentication ​

This authentication layer protects WorkoutKit SDK integrity.

Goal ​

This mechanism protects FizzUp against illicit SDK usage with forged, modified, or replayed workout payloads.

It verifies that workout session payload usage is bound to a valid device/token handshake. Unlike the optional JWT request-authentication layer, this layer is mandatory to launch a workout in the SDK.

The token returned by this handshake is referred to in this documentation as the WorkoutKitToken.

Device-bound token handshake ​

When requesting publicWorkoutSession, the client includes an app-lifecycle-scoped identifier in:

  • X-WorkoutKit-Device request header

The server returns a WorkoutKitToken token through one of these channels:

  • X-WorkoutKit-Token response header
  • GraphQL extensions.workoutkit.token
  • GraphQL workoutKitToken field on session types (WorkoutAudioSession, WorkoutBlockSession, WorkoutVideoSession)

WorkoutKitToken has a validity period of 1 day.

The typical integration flow is to request the session payload when the user chooses the workout they want to launch. In that launch-oriented flow, a one-day validity window is usually more than sufficient.

Verified iOS demo behavior ​

In the iOS demo app, the request interceptor sets:

swift
newRequest.addValue(WorkoutKitConfig.deviceId(), forHTTPHeaderField: "X-WorkoutKit-Device")

Then GetSessionContent extracts the token from GraphQL extensions:

swift
guard let wk = response.extensions?["workoutkit"] as? [String: String],
      let token = wk["token"] else { return }

The token is passed to MonGoModeController or MonVideoGoController for launch.

Expiration and refresh expectations ​

When a WorkoutKitToken expires, fetch a fresh workout session payload and use the new signature returned by the API.

The recommended pattern is:

  1. Let the user choose a workout.
  2. Fetch publicWorkoutSession shortly before launch.
  3. Launch the SDK immediately with the returned payload and signature.

Avoid prefetching launch payloads far in advance when the user is not ready to start the workout yet.

Device Identifier Lifecycle and Privacy Scope ​

X-WorkoutKit-Device is based on a random identifier generated by the SDK. From an integration perspective, it should be treated as app-lifecycle-scoped rather than installation-scoped or as a permanent physical-device identity.

It is generally valid only for the current app lifecycle. When the app quits, the associated token is lost, so a new device/token handshake is required before the workout can be launched again.

This identifier is only needed for session-detail retrieval and SDK launch-token binding. It is not intended to be used by the B2B client as a general-purpose cross-app tracking identifier.

Caching Implications ​

Because the token is bound to the current device/app lifecycle and user session, a cached workout payload cannot be safely reused for multiple end users.

In other words, it is not valid to fetch one workout once and serve that same payload to many different end users.

It is also not valid to rely on that payload for offline workout playback after the app quits, because the launch token must be refreshed through a new handshake.

Media resources such as video and audio assets can still be cached offline. These are handled by SDK-level helpers like AssetManager and StreamManager, not by reusing the GraphQL workout session payload itself.