Skip to main content

MastraAuthFirebase Class

The MastraAuthFirebase class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the experimental_auth option.

Prerequisites​

This example uses Firebase Authentication. Make sure to:

  1. Create a Firebase project in the Firebase Console
  2. Enable Authentication and configure your preferred sign-in methods (Google, Email/Password, etc.)
  3. Generate a service account key from Project Settings > Service Accounts
  4. Download the service account JSON file
FIREBASE_SERVICE_ACCOUNT=/path/to/your/service-account-key.json
FIRESTORE_DATABASE_ID=(default)
# Alternative environment variable names:
# FIREBASE_DATABASE_ID=(default)

Note: Store your service account JSON file securely and never commit it to version control.

Installation​

Before you can use the MastraAuthFirebase class you have to install the @mastra/auth-firebase package.

npm install @mastra/auth-firebase@latest

Usage examples​

Basic usage with environment variables​

If you set the required environment variables (FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID), you can initialize MastraAuthFirebase without any constructor arguments. The class will automatically read these environment variables as configuration:

import { Mastra } from "@mastra/core/mastra";
import { MastraAuthFirebase } from "@mastra/auth-firebase";

// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
export const mastra = new Mastra({
  // ..
  server: {
    experimental_auth: new MastraAuthFirebase(),
  },
});

Custom configuration​

import { Mastra } from "@mastra/core/mastra";
import { MastraAuthFirebase } from "@mastra/auth-firebase";

export const mastra = new Mastra({
  // ..
  server: {
    experimental_auth: new MastraAuthFirebase({
      serviceAccount: "/path/to/service-account.json",
      databaseId: "your-database-id",
    }),
  },
});

Configuration​

The MastraAuthFirebase class can be configured through constructor options or environment variables.

Environment Variables​

  • FIREBASE_SERVICE_ACCOUNT: Path to Firebase service account JSON file
  • FIRESTORE_DATABASE_ID or FIREBASE_DATABASE_ID: Firestore database ID

Note: When constructor options are not provided, the class automatically reads these environment variables. This means you can simply call new MastraAuthFirebase() without any arguments if your environment variables are properly configured.

User Authorization​

By default, MastraAuthFirebase uses Firestore to manage user access. It expects a collection named user_access with documents keyed by user UIDs. The presence of a document in this collection determines whether a user is authorized.

user_access/
  {user_uid_1}/     // Document exists = user authorized
  {user_uid_2}/     // Document exists = user authorized

To customize user authorization, provide a custom authorizeUser function:

import { MastraAuthFirebase } from "@mastra/auth-firebase";

const firebaseAuth = new MastraAuthFirebase({
  authorizeUser: async (user) => {
    // Custom authorization logic
    return user.email?.endsWith("@yourcompany.com") || false;
  },
});

See the MastraAuthFirebase API reference for all available configuration options.

Client-side setup​

When using Firebase auth, you'll need to initialize Firebase on the client side, authenticate users, and retrieve their ID tokens to pass to your Mastra requests.

Setting up Firebase on the client​

First, initialize Firebase in your client application:

import { initializeApp } from "firebase/app";
import { getAuth, GoogleAuthProvider } from "firebase/auth";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
};

const app = initializeApp(firebaseConfig);
export const auth = getAuth(app);
export const googleProvider = new GoogleAuthProvider();

Authenticating users and retrieving tokens​

Use Firebase authentication to sign in users and retrieve their ID tokens:

import { signInWithPopup, signOut, User } from "firebase/auth";
import { auth, googleProvider } from "./firebase";

export const signInWithGoogle = async () => {
  try {
    const result = await signInWithPopup(auth, googleProvider);
    return result.user;
  } catch (error) {
    console.error("Error signing in:", error);
    throw error;
  }
};

export const getIdToken = async (user: User) => {
  try {
    const idToken = await user.getIdToken();
    return idToken;
  } catch (error) {
    console.error("Error getting ID token:", error);
    throw error;
  }
};

export const signOutUser = async () => {
  try {
    await signOut(auth);
  } catch (error) {
    console.error("Error signing out:", error);
    throw error;
  }
};

Refer to the Firebase documentation for other authentication methods like email/password, phone authentication, and more.

Configuring MastraClient​

When experimental_auth is enabled, all requests made with MastraClient must include a valid Firebase ID token in the Authorization header:

import { MastraClient } from "@mastra/client-js";

export const createMastraClient = (idToken: string) => {
  return new MastraClient({
    baseUrl: "https://<mastra-api-url>",
    headers: {
      Authorization: `Bearer ${idToken}`,
    },
  });
};

Note: The ID token must be prefixed with Bearer in the Authorization header.

See Mastra Client SDK for more configuration options.

Making authenticated requests​

Once MastraClient is configured with the Firebase ID token, you can send authenticated requests:

"use client";

import { useAuthState } from 'react-firebase-hooks/auth';
import { MastraClient } from "@mastra/client-js";
import { auth } from '../lib/firebase';
import { getIdToken } from '../lib/auth';

export const TestAgent = () => {
  const [user] = useAuthState(auth);

  async function handleClick() {
    if (!user) return;

    const token = await getIdToken(user);
    const client = createMastraClient(token);

    const weatherAgent = client.getAgent("weatherAgent");
    const response = await weatherAgent.generate({
      messages: "What's the weather like in New York",
    });

    console.log({ response });
  }

  return (
    <button onClick={handleClick} disabled={!user}>
      Test Agent
    </button>
  );
};