Getting Started with GOFA API Integration

Overview

GOFA provides secure APIs for both user-facing and backend system integration, using Firebase for authentication and authorization.

This guide shows how to obtain credentials and tokens, and how to call GOFA APIs securely from both frontend and backend systems.

info

Environment Domains:
- UAT (User Acceptance Testing): www.uat.gofa.app
- Production: www.gofa.app
All example endpoints below use the UAT domain. For production, replace www.uat.gofa.app with www.gofa.app.

---

Authentication Flow Diagram

This diagram shows both the user-facing and backend authentication flows for GOFA API integration.

---

User-facing Website API Integration

Preparation (User-facing)

• Get your clientId and Firebase config: Contact GOFA support to obtain your organization’s clientId and your Firebase config:

  const firebaseConfig = {
    apiKey: "GOFA_FIREBASE_API_KEY",
    authDomain: "GOFA_FIREBASE_AUTH_DOMAIN",
    projectId: "GOFA_FIREBASE_PROJECT_ID",
    // ...other config fields
  };

• Install Firebase SDK (for end-user website integrations only):

  If you are building an end-user website or app that authenticates users and calls APIs requiring a Firebase JWT (User Token), install the Firebase SDK:

  bun add firebase

  or

  npm install firebase

  If you are only calling APIs that require a Client Token (Backend/Admin JWT) from your backend, you do NOT need to install or use Firebase in your project.

---

User Authentication Flow

Option A: Retrieve Firebase Custom Token via GOFA API

1. POST to /api/auth/custom-token:

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

2. Sign in with Firebase using the returned custom token:

   import { initializeApp } from "firebase/app";
   import { getAuth, signInWithCustomToken } from "firebase/auth";
   const app = initializeApp(firebaseConfig);
   const auth = getAuth(app);
   await signInWithCustomToken(auth, "customToken-from-api");

   The custom token is for Firebase Auth sign-in only, not for direct GOFA API access.

---

Option B: Sign In Directly with Firebase, Then Set Claims

1. Sign in with Firebase (email/password, Google, etc.):

   import { getAuth, signInWithEmailAndPassword } from "firebase/auth";
   const auth = getAuth(app);
   const userCredential = await signInWithEmailAndPassword(
     auth,
     "user@example.com",
     "user-password",
   );
   const idToken = await userCredential.user.getIdToken();

2. POST to /api/auth/set-claims:

   { "idToken": "firebase-id-token" }

   This sets the required custom claims for GOFA API access.

---

Calling a GOFA API Endpoint that Requires User Token

See the Challenge Plays API for details on available endpoints and request/response formats for challenge play operations.

After sign-in and claims are set, call protected endpoints like this:

import { getAuth } from "firebase/auth";
const auth = getAuth();
const idToken = await auth.currentUser?.getIdToken();

const response = await fetch("https://www.uat.gofa.app/api/challenge-plays", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${idToken}`,
  },
  body: JSON.stringify({
    challengeId: "abc123",
    score: 42,
  }),
});

const result = await response.json();
console.log(result);

• Always include the Authorization: Bearer <idToken> header.

---

Backend/Admin API Integration

Preparation (Backend/Admin)

• Get your clientId and clientSecret: Contact GOFA support to obtain your organization’s clientId and clientSecret (required for backend authentication).

---

Retrieve the ClientToken

// Example using Node.js (fetch or axios)
const response = await fetch("https://www.uat.gofa.app/api/client/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  }),
});
const data = await response.json();
const clientToken = data.token; // Use this as the ClientToken

Call the protected endpoint with the ClientToken

const clientId = "your-client-id";
const response2 = await fetch(
  `https://www.uat.gofa.app/api/client/${clientId}/users`,
  {
    method: "GET", // or POST, PATCH, DELETE as required
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${clientToken}`,
    },
    // body: JSON.stringify({ ... }) // for POST/PATCH requests
  },
);
const result = await response2.json();
console.log(result);

• Always include the Authorization: Bearer <ClientToken> header for backend-to-backend API calls.
• Replace the method and body as needed for your use case.

---

Notes

• For Google/social login, always use the Firebase JS SDK, then call /api/auth/set-claims.
• Always use HTTPS and never log user credentials or tokens.
• All error responses include an error field with a descriptive message.
• Contact GOFA support for your Firebase config and any integration questions.

---