MastraAuthBetterAuth class

The MastraAuthBetterAuth class provides authentication for Mastra applications using Better Auth. It verifies incoming requests with Better Auth sessions and integrates with the Mastra server using the auth option.

Usage example

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthBetterAuth } from '@mastra/auth-better-auth'
import { betterAuth } from 'better-auth'

// Create your Better Auth instance
const auth = betterAuth({
  database: {
    provider: 'postgresql',
    url: process.env.DATABASE_URL,
  },
  emailAndPassword: {
    enabled: true,
  },
  baseURL: process.env.BETTER_AUTH_URL,
  secret: process.env.BETTER_AUTH_SECRET,
})

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthBetterAuth({
      auth,
    }),
  },
})

Constructor parameters

auth?:

Auth

Your Better Auth instance created via betterAuth({ ... }), configured with a supported database provider. Optional when secret is provided, in which case the provider builds its own instance in init() on the host's auth database and owns its schema migrations.

secret?:

string

Secret used to sign sessions for the instance the provider builds itself. Required when auth is omitted. Ignored when auth is provided.

signUpEnabled?:

boolean

= true

Whether new users can register via sign-up. Set to false to disable public registration. Only applies to the instance the provider builds itself. When you pass auth, disable sign-up in your Better Auth configuration instead.

name?:

string

= 'better-auth'

Custom name for the auth provider instance.

authorizeUser?:

(user: BetterAuthUser, request: MastraAuthRequest) => Promise<boolean> | boolean

Custom authorization function to determine if a user should be granted access. Called after session verification. By default, allows all authenticated users with valid sessions.

public?:

Array<string | RegExp | [string, Methods | Methods[]]>

Public routes that do not require authentication. Supports exact paths, wildcards, and path params.

protected?:

Array<string | RegExp | [string, Methods | Methods[]]>

Protected routes that require authentication. Supports exact paths, wildcards, and path params.

BetterAuthUser type

The BetterAuthUser type contains the session and user information returned by Better Auth:

interface BetterAuthUser {
  session: Session & { activeOrganizationId?: string | null }
  user: User
}

• session: The Better Auth session object containing session metadata. activeOrganizationId comes from the organization plugin. The provider registers that plugin only on the instance it builds itself. When you pass auth, add the plugin to that instance if you use organization features.
• user: The authenticated user object with user details

The Session and User types are exported by the Better Auth package.

Matching rules

• public and protected accept exact paths, wildcard patterns (like /api/*), and path params (like /users/:id).
• For method-specific rules, use tuples like ["/api/agents", ["GET", "POST"]].
• If a route matches both public and protected, public wins and no auth is required, unless the route is marked requiresAuth: true. Those routes still authenticate.
• If neither matches, a route requires auth when it's under /api/* (the built-in default protected pattern) or is a custom route registered with registerApiRoute() that isn't marked requiresAuth: false, and other paths don't require auth.

Related

MastraAuthBetterAuth Class