Clerk

The @mastra/auth-clerk package provides authentication for Mastra using Clerk. It verifies incoming requests using Clerk's authentication system and integrates with the Mastra server using the auth option.

Prerequisites

This example uses Clerk authentication. Make sure to add your Clerk credentials to your .env file and ensure your Clerk project is properly configured.

.env

CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
CLERK_JWKS_URI=https://your-clerk-domain.clerk.accounts.dev/.well-known/jwks.json

备注

You can find these keys in your Clerk Dashboard under "API Keys".

Installation

Before you can use the MastraAuthClerk class you have to install the @mastra/auth-clerk package.

npm

npm install @mastra/auth-clerk@latest

pnpm

pnpm add @mastra/auth-clerk@latest

Yarn

yarn add @mastra/auth-clerk@latest

Bun

bun add @mastra/auth-clerk@latest

Usage example

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthClerk } from '@mastra/auth-clerk'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthClerk({
      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
      secretKey: process.env.CLERK_SECRET_KEY,
      jwksUri: process.env.CLERK_JWKS_URI,
    }),
  },
})

备注

The default authorizeUser method allows all authenticated users. To customize user authorization, provide a custom authorizeUser function when constructing the provider.

Visit MastraAuthClerk for all available configuration options.

Client-side setup

When using Clerk auth, you'll need to retrieve the access token from Clerk on the client side and pass it to your Mastra requests.

Retrieving the access token

Use the Clerk React hooks to authenticate users and retrieve their access token:

lib/auth.ts

import { useAuth } from '@clerk/nextjs'

export const useClerkAuth = () => {
  const { getToken } = useAuth()

  const getAccessToken = async () => {
    const token = await getToken()
    return token
  }

  return { getAccessToken }
}

Refer to the Clerk documentation for more information.

Configuring MastraClient

When auth is enabled, all requests made with MastraClient must include a valid Clerk access token in the Authorization header:

lib/mastra/mastra-client.ts

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

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

备注

The access token must be prefixed with Bearer in the Authorization header.

Visit Mastra Client SDK for more configuration options.

Making authenticated requests

Once MastraClient is configured with the Clerk access token, you can send authenticated requests:

React

src/components/test-agent.tsx

'use client'

import { useAuth } from '@clerk/nextjs'
import { MastraClient } from '@mastra/client-js'

export const TestAgent = () => {
  const { getToken } = useAuth()

  async function handleClick() {
    const token = await getToken()

    const client = new MastraClient({
      baseUrl: 'http://localhost:4111',
      headers: token ? { Authorization: `Bearer ${token}` } : undefined,
    })

    const weatherAgent = client.getAgent('weatherAgent')
    const response = await weatherAgent.generate("What's the weather like in New York")

    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-clerk-access-token>" \
  -d '{
    "messages": "Weather in London"
  }'