Skip to main content

MastraAuthAuth0 Class

The MastraAuthAuth0 class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the experimental_auth option.

Usage example​

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { MastraAuthAuth0 } from "@mastra/auth-auth0";

export const mastra = new Mastra({
  // ..
  server: {
    experimental_auth: new MastraAuthAuth0({
      domain: process.env.AUTH0_DOMAIN,
      audience: process.env.AUTH0_AUDIENCE,
    }),
  },
});

Note: You can omit the constructor parameters if you have the appropriately named environment variables (AUTH0_DOMAIN and AUTH0_AUDIENCE) set. In that case, simply use new MastraAuthAuth0() without any arguments.

Constructor parameters​

domain?:

string
= process.env.AUTH0_DOMAIN
Your Auth0 domain (e.g., your-tenant.auth0.com). This is used to verify JWT tokens issued by your Auth0 tenant.

audience?:

string
= process.env.AUTH0_AUDIENCE
Your Auth0 API identifier/audience. This ensures tokens are intended for your specific API.

name?:

string
= "auth0"
Custom name for the auth provider instance.

authorizeUser?:

(user: Auth0User) => Promise<boolean> | boolean
Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users with valid tokens.

Environment Variables​

The following environment variables are automatically used when constructor options are not provided:

AUTH0_DOMAIN?:

string
Your Auth0 domain. Can be found in your Auth0 Dashboard under Applications > Settings.

AUTH0_AUDIENCE?:

string
Your Auth0 API identifier. This is the identifier you set when creating an API in your Auth0 Dashboard.

Default Authorization Behavior​

By default, MastraAuthAuth0 validates Auth0 JWT tokens and allows access to all authenticated users:

  1. Token Verification: The JWT token is verified using Auth0's public keys (JWKS)
  2. Signature Validation: Ensures the token was signed by your Auth0 tenant
  3. Expiration Check: Verifies the token has not expired
  4. Audience Validation: Confirms the token was issued for your specific API (audience)
  5. Issuer Validation: Ensures the token was issued by your Auth0 domain

If all validations pass, the user is considered authorized. To implement custom authorization logic (e.g., role-based access control), provide a custom authorizeUser function.

Auth0 User Type​

The Auth0User type used in the authorizeUser function corresponds to the decoded JWT token payload, which typically includes:

  • sub: The user's unique identifier (subject)
  • email: The user's email address (if included in token)
  • 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)
  • iss: Token issuer (your Auth0 domain)
  • aud: Token audience (your API identifier)
  • iat: Token issued at timestamp
  • exp: Token expiration timestamp
  • scope: Granted scopes for the token
  • Custom claims and app metadata configured in your Auth0 tenant

The exact properties available depend on your Auth0 configuration, scopes requested, and any custom claims you've configured.

MastraAuthAuth0 Class

On this page