JSON Web Token
Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference
Published: 2026-05-10 · Source: crawler_authoritative
Tình huống
Guide for configuring JWT-based authentication in Mastra using the MastraJwtAuth class, targeting developers integrating Mastra server with authentication.
Insight
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:
npm install @mastra/auth@latestpnpm:
pnpm add @mastra/auth@latestYarn:
yarn add @mastra/auth@latestBun:
bun add @mastra/auth@latestCreating 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:
- Select JWT Encoder.
- Scroll down to the Sign JWT: Secret section.
- Enter your secret (for example:
supersecretdevkeythatishs256safe!). - Click Generate example to create a valid JWT.
- Copy the generated token and set it as
MASTRA_JWT_TOKENin your.envfile.
Usage example
Take your generated JWT and use it to configure MastraJwtAuth in your Mastra server:
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 for all available configuration options.
Inside Studio, 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:
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 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:
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:
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"
}'Hành động
- Install @mastra/auth@latest via npm, pnpm, yarn, or bun. 2. Generate a JWT using jwt.io: select JWT Encoder, enter your MASTRA_JWT_SECRET in the Sign JWT section, generate the token, and copy it. 3. Set MASTRA_JWT_TOKEN in your .env file with the generated token. 4. Configure MastraJwtAuth in your Mastra server with the secret from environment variables. 5. In Mastra Studio, add an Authorization header with value Bearer
. 6. Configure MastraClient with the baseUrl and Authorization header containing Bearer ${MASTRA_JWT_TOKEN}. 7. Make authenticated requests using agent.generate() or curl with the Authorization: Bearer header.
Kết quả
Incoming requests are verified against the shared secret. Requests with valid JWTs in the Authorization: Bearer header are authenticated and allowed to access Mastra server endpoints. MastraClient requests with valid tokens successfully communicate with the Mastra API.
Điều kiện áp dụng
Requires @mastra/auth@latest package. The secret must be HS256-safe as specified in jwt.io generation.
Nội dung gốc (Original)
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:
npm install @mastra/auth@latestpnpm:
pnpm add @mastra/auth@latestYarn:
yarn add @mastra/auth@latestBun:
bun add @mastra/auth@latestCreating 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:
- Select JWT Encoder.
- Scroll down to the Sign JWT: Secret section.
- Enter your secret (for example:
supersecretdevkeythatishs256safe!). - Click Generate example to create a valid JWT.
- Copy the generated token and set it as
MASTRA_JWT_TOKENin your.envfile.
Usage example
Take your generated JWT and use it to configure MastraJwtAuth in your Mastra server:
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 for all available configuration options.
Inside Studio, 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:
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 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:
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:
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"
}'Liên kết
- Nền tảng: Dev Framework · Mastra
- Nguồn: https://mastra.ai/docs/server/auth/jwt
Xem thêm: