Authentication

TrainingKit has two runtime authentication contracts, plus a build-time key used only for schema introspection. The contracts themselves are defined in the API section; this page shows how each one surfaces in the Flutter bridge.

The two runtime contracts

Contract	What it protects	How it travels	Required?
API Authentication	Your B2B API perimeter — only your authenticated backend context can call the API	A backend-issued JWT sent on your GraphQL requests	When enabled in your Admin Console (recommended for production)
SDK Authentication	TrainingKit integrity — blocks forged, modified, or replayed workout payloads	The X-TrainingKit-Device handshake that returns a TrainingKitToken, forwarded to the native SDK on launch	Always — it is mandatory to launch a workout

Full reference:

• API Authentication
• SDK Authentication

API Authentication (request JWT)

Your backend issues a short-lived JWT (signed with your RSA/ECDSA key, carrying a sub claim for the end user) and your app attaches it to every GraphQL request — typically an Authorization: Bearer <jwt> header. The API layer validates it; the SDK does not. This layer is turned on and configured (public keys, JWKS/PEM) by the B2B client in the Admin Console.

Add it alongside the device header when you build the client:

import 'package:graphql_flutter/graphql_flutter.dart';
import 'package:trainingkit_flutter/trainingkit_flutter.dart';

final deviceId = await deviceIdentifier();

final link = HttpLink(
  'https://your-graphql-endpoint/graphql',
  defaultHeaders: {
    'X-TrainingKit-Device': deviceId,
    'Authorization': 'Bearer $backendJWT', // API Authentication, when enabled
  },
);

Issue the JWT server-side only; never embed the signing key in the app.

SDK Authentication (device handshake + TrainingKitToken)

Launching a workout requires a device-bound token, and the bridge handles most of it for you.

1. Send the SDK device identifier on every GraphQL request (the X-TrainingKit-Device header above). deviceIdentifier() returns it as a Future<String> — read it once and reuse it.
2. The backend returns a TrainingKitToken in the session payload (the trainingKitToken field, also available via GraphQL extensions.trainingkit.token or the X-TrainingKit-Token header).
3. Pass the full session map to launchWorkout — it reads trainingKitToken and forwards it to the native SDK:

await launchWorkout(session); // throws TrainingKitException if trainingKitToken is missing

The token is valid for one day and bound to the current app lifecycle, so fetch the full session shortly before launch. See SDK Authentication for lifecycle, caching, and refresh rules.

Build-time only: X-Developer-Authorization-Key

This is not a runtime credential. It unlocks GraphQL schema introspection (for the Admin Console Playground or code generation) and is retrieved from your Admin Console API settings.

Use it only on developer machines or CI, for tooling such as schema introspection. Never ship it in the app build or hard-code it in source that ends up in the binary.