@mastra/core/dist/docs/references/reference-auth-firebase.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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 `auth` option.

## Usage examples

### Basic usage with environment variables

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthFirebase } from '@mastra/auth-firebase'

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

### Custom configuration

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthFirebase } from '@mastra/auth-firebase'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthFirebase({
      serviceAccount: '/path/to/service-account-key.json',
      databaseId: 'your-database-id',
    }),
  },
})
```

## Constructor parameters

**serviceAccount** (`string`): Path to the Firebase service account JSON file. This file contains the credentials needed to verify Firebase ID tokens on the server side. (Default: `process.env.FIREBASE_SERVICE_ACCOUNT`)

**databaseId** (`string`): The Firestore database ID to use. Typically '(default)' for the default database. (Default: `process.env.FIRESTORE_DATABASE_ID || process.env.FIREBASE_DATABASE_ID`)

**name** (`string`): Custom name for the auth provider instance. (Default: `"firebase"`)

**authorizeUser** (`(user: FirebaseUser) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks for the presence of a document in the 'user\_access' collection keyed by the user's UID.

## Environment variables

The following environment variables are automatically used when constructor options aren't provided:

**FIREBASE\_SERVICE\_ACCOUNT** (`string`): Path to Firebase service account JSON file. Used if serviceAccount option is not provided.

**FIRESTORE\_DATABASE\_ID** (`string`): Firestore database ID. Primary environment variable for database configuration.

**FIREBASE\_DATABASE\_ID** (`string`): Alternative environment variable for Firestore database ID. Used if FIRESTORE\_DATABASE\_ID is not set.

## Default authorization behavior

By default, `MastraAuthFirebase` uses Firestore to manage user access:

1. After successfully verifying a Firebase ID token, the `authorizeUser` method is called
2. It checks for the existence of a document in the `user_access` collection with the user's UID as the document ID
3. If the document exists, the user is authorized; otherwise, access is denied
4. The Firestore database used is determined by the `databaseId` parameter or environment variables

## Firebase user type

The `FirebaseUser` type used in the `authorizeUser` function corresponds to Firebase's `DecodedIdToken` interface, which includes:

- `uid`: The user's unique identifier
- `email`: The user's email address (if available)
- `email_verified`: Whether the email is verified
- `name`: The user's display name (if available)
- `picture`: URL to the user's profile picture (if available)
- `auth_time`: When the user authenticated
- And other standard JWT claims

## Related

[MastraAuthFirebase Class](https://mastra.ai/docs/server/auth/firebase)