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>
  );
};

const express = require('express');
const admin = require('firebase-admin');
const { MastraClient } = require('@mastra/client-js');
 
// Initialize Firebase Admin
admin.initializeApp({
  credential: admin.credential.cert({
    // Your service account credentials
  })
});
 
const app = express();
app.use(express.json());
 
app.post('/generate', async (req, res) => {
  try {
    const { idToken } = req.body;
    
    // Verify the token
    await admin.auth().verifyIdToken(idToken);
 
    const mastra = new MastraClient({
      baseUrl: "http://localhost:4111",
      headers: {
        Authorization: `Bearer ${idToken}`
      }
    });
 
    const weatherAgent = mastra.getAgent("weatherAgent");
    const response = await weatherAgent.generate({
      messages: "What's the weather like in Nairobi"
    });
 
    res.json({ response: response.text });
  } catch (error) {
    res.status(401).json({ error: 'Unauthorized' });
  }
});

curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-firebase-id-token>" \
  -d '{
    "messages": "Weather in London"
  }'