# Auth0
The `@mastra/auth-auth0` package provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `auth` option.
## Prerequisites
This example uses Auth0 authentication. Make sure to:
1. Create an Auth0 account at [auth0.com](https://auth0.com/)
2. Set up an Application in your Auth0 Dashboard
3. Configure an API in your Auth0 Dashboard with an identifier (audience)
4. Configure your application's allowed callback URLs, web origins, and logout URLs
```env
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_AUDIENCE=your-api-identifier
```
> **Note:** You can find your domain in the Auth0 Dashboard under Applications > Settings. The audience is the identifier of your API configured in Auth0 Dashboard > APIs.
>
> For detailed setup instructions, refer to the [Auth0 quickstarts](https://auth0.com/docs/quickstarts) for your specific platform.
## Installation
Before you can use the `MastraAuthAuth0` class you have to install the `@mastra/auth-auth0` package.
**npm**:
```bash
npm install @mastra/auth-auth0@latest
```
**pnpm**:
```bash
pnpm add @mastra/auth-auth0@latest
```
**Yarn**:
```bash
yarn add @mastra/auth-auth0@latest
```
**Bun**:
```bash
bun add @mastra/auth-auth0@latest
```
## Usage examples
### Basic usage with environment variables
```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
export const mastra = new Mastra({
server: {
auth: new MastraAuthAuth0(),
},
})
```
### Custom configuration
```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
export const mastra = new Mastra({
server: {
auth: new MastraAuthAuth0({
domain: process.env.AUTH0_DOMAIN,
audience: process.env.AUTH0_AUDIENCE,
}),
},
})
```
## Configuration
### User Authorization
By default, `MastraAuthAuth0` allows all authenticated users who have valid Auth0 tokens for the specified audience. The token verification ensures that:
1. The token is properly signed by Auth0
2. The token isn't expired
3. The token audience matches your configured audience
4. The token issuer matches your Auth0 domain
To customize user authorization, provide a custom `authorizeUser` function:
```typescript
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
const auth0Provider = new MastraAuthAuth0({
authorizeUser: async user => {
// Custom authorization logic
return user.email?.endsWith('@yourcompany.com') || false
},
})
```
> **Info:** Visit [MastraAuthAuth0](https://mastra.ai/reference/auth/auth0) for all available configuration options.
## Client-side setup
When using Auth0 auth, you'll need to set up the Auth0 React SDK, authenticate users, and retrieve their access tokens to pass to your Mastra requests.
### Setting up Auth0 React SDK
First, install and configure the Auth0 React SDK in your application:
**npm**:
```bash
npm install @auth0/auth0-react
```
**pnpm**:
```bash
pnpm add @auth0/auth0-react
```
**Yarn**:
```bash
yarn add @auth0/auth0-react
```
**Bun**:
```bash
bun add @auth0/auth0-react
```
```typescript
import React from 'react'
import { Auth0Provider } from '@auth0/auth0-react'
const Auth0ProviderWithHistory = ({ children }) => {
return (
{children}
)
}
export default Auth0ProviderWithHistory
```
### Retrieving access tokens
Use the Auth0 React SDK to authenticate users and retrieve their access tokens:
```typescript
import { useAuth0 } from '@auth0/auth0-react'
export const useAuth0Token = () => {
const { getAccessTokenSilently } = useAuth0()
const getAccessToken = async () => {
const token = await getAccessTokenSilently()
return token
}
return { getAccessToken }
}
```
> **Note:** Refer to the [Auth0 React SDK documentation](https://auth0.com/docs/libraries/auth0-react) for more authentication methods and configuration options.
## Configuring `MastraClient`
When `auth` is enabled, all requests made with `MastraClient` must include a valid Auth0 access token in the `Authorization` header:
```typescript
import { MastraClient } from '@mastra/client-js'
export const createMastraClient = (accessToken: string) => {
return new MastraClient({
baseUrl: 'https://',
headers: {
Authorization: `Bearer ${accessToken}`,
},
})
}
```
> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
>
> Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
### Making authenticated requests
Once `MastraClient` is configured with the Auth0 access token, you can send authenticated requests:
**React**:
```tsx
import React, { useState } from 'react'
import { useAuth0 } from '@auth0/auth0-react'
import { MastraClient } from '@mastra/client-js'
export const MastraApiTest = () => {
const { getAccessTokenSilently } = useAuth0()
const [result, setResult] = useState(null)
const callMastraApi = async () => {
const token = await getAccessTokenSilently()
const mastra = new MastraClient({
baseUrl: 'http://localhost:4111',
headers: {
Authorization: `Bearer ${token}`,
},
})
const weatherAgent = mastra.getAgent('weatherAgent')
const response = await weatherAgent.generate("What's the weather like in New York")
setResult(response.text)
}
return (