User authentication

This page describes the Firebase flows used by existing user-facing integrations. A Firebase custom token is for Firebase SDK sign-in. After sign-in, obtain a Firebase ID token and send that ID token to a protected GOFA user route.

Password sign-in through GOFA

POST /api/auth/custom-token

Send the following JSON from the user-facing integration:

Content-Type: application/json

{
  "clientId": "your-client-id",
  "email": "user@example.com",
  "password": "user-password"
}

The optional grantType field may be set to "password". The request is strict: unknown fields are rejected.

The endpoint verifies the password with Firebase, resolves the user in the client directory, and requires an active Firebase account with player.status: "active".

Success response

{
  "customToken": "<firebase-custom-token>",
  "user": {
    "uid": "<firebase-uid>",
    "email": "user@example.com",
    "displayName": "Example User",
    "photoURL": null,
    "emailVerified": false,
    "disabled": false
  }
}

Use the returned token immediately with the Firebase client SDK:

const credential = await signInWithCustomToken(auth, data.customToken);
const idToken = await credential.user.getIdToken();

The custom token is not a direct GOFA API credential. Use the resulting Firebase ID token as Authorization: Bearer <firebase-id-token> where a user token is accepted. The endpoint does not expose a custom-token TTL; obtain fresh Firebase tokens through the SDK rather than caching the exchange result.

Error responses

The server may return a more specific message for the same error code, so clients should branch on the HTTP status and code rather than a human-readable message.

Direct Firebase sign-in and claims

An integration that signs in directly with Firebase (for example with an OAuth provider) can request GOFA claims after it has an ID token.

POST /api/auth/set-claims

Content-Type: application/json

{
  "clientId": "your-client-id",
  "idToken": "<firebase-id-token>"
}

The endpoint verifies the ID token and uses the UID inside that token to find the client user. It does not accept a separate target UID. For a normal client, the signed-in user must have a corresponding client-user record.

Success response

{
  "success": true,
  "claims": {
    "your-client-id": {
      "player": {
        "status": "active"
      }
    }
  },
  "user": {
    "uid": "<firebase-uid>",
    "email": "user@example.com",
    "displayName": "Example User",
    "photoURL": null,
    "emailVerified": false,
    "disabled": false
  }
}

The returned claims are also written to Firebase Auth. Refresh the ID token through the Firebase SDK before calling a route that depends on newly written claims.

Typical errors are 400 for a missing clientId or idToken, 401 for an invalid ID token, 404 when the client user cannot be found, and 500 for a server error. Some internal session types can receive 403; they are not a public user-authentication grant.

Exchange an existing Firebase session

POST /api/auth/exchange-token

This route is for an integration that already has a valid Firebase session and needs a Firebase custom token for a GOFA web-module handoff.

Authorization: Bearer <firebase-id-token>

No request body is required. The client ID is derived from the request hostname. The server verifies the ID token, finds that UID under the hostname's client, and returns:

{
  "customToken": "<firebase-custom-token>"
}

The response is 401 for a missing or invalid bearer token, 404 when the client user is not found, and 500 for a server error. Approved cross-origin callers must also satisfy the route's CORS allowlist.

For a supported GOFA web-module handoff, pass the custom token in the module's documented customToken query parameter. The web app can consume that token to establish a browser session. Do not use this custom token as a bearer token for the client API.

Website registration boundary

Website registration is handled by the GOFA website flow. This guide does not define a public register endpoint or a client-user creation workflow.