SDK authentication

The GOFA Lessons and WebView Flutter SDKs sign a member in to Firebase before opening GOFA features. A Firebase custom token is used once to sign in; the resulting Firebase ID token represents the signed-in member on protected user routes. A ClientToken is a separate backend credential for privileged client API operations. It is not an SDK member sign-in token.

Choose your path

• Existing app using clientSecret: Continue its current sign-in path while planning a coordinated migration with GOFA. Treat an app-embedded secret as exposed, and account for older app versions before rotation.
• New app or migration to backend-mediated sign-in: The design below is being prepared. It is not yet a released production integration. Confirm SDK version, GOFA endpoint enablement, Firebase project, and rollout plan with GOFA before using it.
• Backend requiring /api/client administration: Use Client tokens from a trusted backend. Do not send the client secret or ClientToken to the app.

Planned server-mediated member sign-in

The partner app continues to authenticate its member in the partner's own system. The partner backend then requests a GOFA Firebase custom token for that same member:

1. The app calls its own backend using the member's normal authenticated session. The backend validates that session and derives a stable member ID from its own trusted records. It must not accept an arbitrary member ID supplied by the app for this exchange.
2. The backend calls POST /api/auth/custom-token with a dedicated external_user_sso key stored in its secret manager. The request has grantType: "external_user" and externalUserId set to the stable member ID. The key identifies the GOFA client; do not send clientId, roles, claims, email, or a client secret in this request.
3. The backend returns only the short-lived customToken to that authenticated app session over HTTPS. The app's SDK token provider supplies a fresh token when GOFA needs to sign in or open a WebView. Do not log or persist the token.

Partner backend example

The partner backend must obtain the GOFA SSO key from server-only storage. The authenticated session and member lookup below represent the partner's existing backend authentication; they are not GOFA endpoints.

const member = await requireAuthenticatedMember(request);
const gofaSsoKey = await getGofaSsoKeyFromSecretManager();

const response = await fetch('https://www.gofa.app/api/auth/custom-token', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${gofaSsoKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grantType: 'external_user',
    externalUserId: member.stableId,
  }),
});
if (!response.ok) throw new Error(`GOFA sign-in failed: ${response.status}`);

const { customToken } = await response.json();
return Response.json(
  { customToken },
  { headers: { 'Cache-Control': 'no-store' } },
);

Use https://www.uat.gofa.app/api/auth/custom-token and a separate UAT key while testing. Never reuse the SSO key as a Commercial API key or a client secret for POST /api/client/token.

Flutter WebView example

fetchGofaCustomToken() calls the partner backend with the member's authenticated app session. The clientUserId must match the stable ID the backend sends as externalUserId.

await WebViewSdkManager().init(
  clientId: 'your-client-id',
  clientUserId: stableMemberId,
  customTokenProvider: () async => partnerBackend.fetchGofaCustomToken(),
  environment: Environment.PRD,
);

For GOFA Lessons, use the same provider with an explicit member ID in params:

await LessonSdkManager().init(
  environment: Environment.PRD,
  params: {
    'clientId': 'your-client-id',
    'clientUserId': stableMemberId,
  },
  customTokenProvider: () async => partnerBackend.fetchGofaCustomToken(),
);

In provider mode, omit clientSecret; the SDK accepts exactly one token source. The GOFA backend key must never be included in Flutter code, build arguments, assets, URLs, or client logs.

Migration checks before production cutover

• Confirm the production and UAT Firebase projects and GOFA client IDs.
• Preserve each existing member's exact GOFA identity mapping and data, including members previously identified by a device-derived ID. A new member ID can create a different account instead of opening existing data.
• Agree whether existing member records need a backfill or approved just-in-time provisioning before sign-in.
• Test the partner backend, Flutter app, GOFA WebView or Lessons flow, and older app versions together. Keep the legacy sign-in path available until the rollout accounts for those versions.
• Rotate or revoke the app-exposed secret only after the replacement is deployed, verified, and no required app version depends on it. Revoking the secret stops new token issuance; already issued ClientTokens may remain usable until their expiry.

For the existing SDK setup and MSK WebView handoff, see WebView getting started, Lessons code setup, and MSK authentication.