Clerk
Use Clerk with Mastra in two ways:
- Agent tools let an agent manage Clerk users, organizations, and sessions through Mastra Connect.
- Server authentication verifies requests to your Mastra server with Clerk, using the
@mastra/auth-clerkpackage.
ConnectDirect link to Connect
Before you start, complete the Connect setup to install @mastra/connect and configure your platform project.
Agent toolsDirect link to Agent tools
Give agents tools to manage users, organizations, memberships, invitations, roles, and sessions in Clerk.
Connect an account with the clerk provider ID. Run this command from the directory that contains your .env file:
mastra connect add clerk
Then pass tools() to the agent and select the provider:
import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'
export const clerkAgent = new Agent({
id: 'clerk-agent',
name: 'Clerk agent',
instructions:
'You help people manage users, organizations, memberships, invitations, roles, and sessions in Clerk.',
model: '__GATEWAY_OPENAI_MODEL_LUNA__',
tools: tools({ providers: ['clerk'] }),
})
The agent gets 42 Clerk tools, with keys such as clerk_assign_organization_role_permission. See Clerk tools for the full list, and the tools() parameters to restrict tools or require approval before a call runs.
Server authenticationDirect link to Server authentication
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.
PrerequisitesDirect link to Prerequisites
This example uses Clerk authentication. Ensure you add your Clerk credentials to your .env file and ensure your Clerk project is configured correctly.
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".
InstallationDirect link to Installation
Before you can use the MastraAuthClerk class you have to install the @mastra/auth-clerk package.
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/auth-clerk@latest
pnpm add @mastra/auth-clerk@latest
yarn add @mastra/auth-clerk@latest
bun add @mastra/auth-clerk@latest
Usage exampleDirect link to Usage example
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 setupDirect link to 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 tokenDirect link to Retrieving the access token
Use the Clerk React hooks to authenticate users and retrieve their access token:
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 MastraClientDirect link to configuring-mastraclient
When auth is enabled, all requests made with MastraClient must include a valid Clerk access token in the Authorization header:
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 requestsDirect link to Making authenticated requests
Once MastraClient is configured with the Clerk access token, you can send authenticated requests:
- React
- cURL
'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 -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"
}'