@mastra/core/dist/docs/references/docs-server-auth-jwt.md

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

# JSON Web Token

The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `auth` option.

## Installation

Before you can use the `MastraJwtAuth` class you have to install the `@mastra/auth` package.

**npm**:

```bash
npm install @mastra/auth@latest
```

**pnpm**:

```bash
pnpm add @mastra/auth@latest
```

**Yarn**:

```bash
yarn add @mastra/auth@latest
```

**Bun**:

```bash
bun add @mastra/auth@latest
```

## Creating a JWT

To authenticate requests to your Mastra server, you'll need a valid JSON Web Token (JWT) signed with your `MASTRA_JWT_SECRET`.

The easiest way to generate one is using [jwt.io](https://www.jwt.io/):

1. Select **JWT Encoder**.
2. Scroll down to the **Sign JWT: Secret** section.
3. Enter your secret (for example: `supersecretdevkeythatishs256safe!`).
4. Click **Generate example** to create a valid JWT.
5. Copy the generated token and set it as `MASTRA_JWT_TOKEN` in your `.env` file.

## Usage example

Take your generated JWT and use it to configure `MastraJwtAuth` in your Mastra server:

```typescript
import { Mastra } from '@mastra/core'
import { MastraJwtAuth } from '@mastra/auth'

export const mastra = new Mastra({
  server: {
    auth: new MastraJwtAuth({
      secret: process.env.MASTRA_JWT_SECRET,
    }),
  },
})
```

> **Info:** Visit [MastraJwtAuth](https://mastra.ai/reference/auth/jwt) for all available configuration options.

Inside [Studio](https://mastra.ai/docs/studio/overview), go to **Settings** and under **Headers** select the **"Add Header"** button. Enter `Authorization` as the header name and `Bearer <your-jwt>` as the value.

## Configuring `MastraClient`

When `auth` is enabled, all requests made with `MastraClient` must include a valid JWT in the `Authorization` header:

```typescript
import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: 'https://<mastra-api-url>',
  headers: {
    Authorization: `Bearer ${process.env.MASTRA_JWT_TOKEN}`,
  },
})
```

> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.

### Making authenticated requests

Once `MastraClient` is configured, you can send authenticated requests from your frontend application, or use `curl` for quick local testing:

**React**:

```tsx
import { mastraClient } from '../../lib/mastra-client'

export const TestAgent = () => {
  async function handleClick() {
    const agent = mastraClient.getAgent('weatherAgent')

    const response = await agent.generate('Weather in London')

    console.log(response)
  }

  return <button onClick={handleClick}>Test Agent</button>
}
```

**cURL**:

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