Authenticate API requests with a Firebase ID token sent as a Bearer token, and refresh it before it expires.

Nucleus OS uses Firebase Authentication for sign-in. API requests that act on behalf of a user carry that user's Firebase ID token in the Authorization header:

POST /graphql HTTP/1.1
Host: <api-host>
Content-Type: application/json
Authorization: Bearer <firebase-id-token>

Public operations, such as jobPostings or createSupportRequest, do not require the header.

Getting a token

After the user signs in with the Firebase Web SDK, read the current user's ID token. The SDK caches it and refreshes it automatically when it is close to expiry.

import { getAuth } from "firebase/auth";
 
const user = getAuth().currentUser;
if (!user) throw new Error("Not signed in");
 
const idToken = await user.getIdToken(); // cached; refreshed when needed
 
const res = await fetch("https://<api-host>/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${idToken}`,
  },
  body: JSON.stringify({ query: "{ __typename }" }),
});

Token lifetime

Firebase ID tokens are short-lived (about one hour). When a token expires, the API responds with an UNAUTHENTICATED error. Refresh the token and retry the request once:

async function gql(query: string, variables?: object, retry = true) {
  const token = await getAuth().currentUser!.getIdToken();
  const res = await fetch("https://<api-host>/graphql", {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
    body: JSON.stringify({ query, variables }),
  });
  const body = await res.json();
  const unauthenticated = body.errors?.some(
    (e: { code?: string }) => e.code === "UNAUTHENTICATED",
  );
  if (unauthenticated && retry) {
    await getAuth().currentUser!.getIdToken(true); // force refresh
    return gql(query, variables, false);
  }
  return body;
}

Authentication errors

Message	Meaning	What to do
`Authorization header is required`	The operation needs a signed-in user and no token was sent.	Send `Authorization: Bearer <token>`.
`Invalid Firebase ID token`	The token is malformed, expired, or from another project.	Refresh the token; check that you are signed in to the right project.
`Authentication required` / permission messages	The token is valid but the user lacks the required role.	Use an account with the right role.

See Errors for the full error format.

Keep tokens out of logs

An ID token grants the same access as the signed-in user until it expires. Do not log tokens, put them in URLs, or share them between users.

Authentication

Getting a token

Token lifetime

Authentication errors

On this page