MastraAuthClerk class

The MastraAuthClerk class provides authentication for Mastra applications using Clerk. It verifies incoming requests with Clerk-issued JWT tokens and integrates with the Mastra server using the auth option.

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({
      jwksUri: process.env.CLERK_JWKS_URI,
      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
      secretKey: process.env.CLERK_SECRET_KEY,
    }),
  },
})

Restricting login to a single organization

Set organizationId or organizationSlug to only allow members of a specific Clerk organization to sign in. Non-members are rejected during authorization. Configure only one of the two. Setting both throws at startup, so login can't be granted to two different organizations.

src/mastra/index.ts

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

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

User ID

The authenticated user's id is the token's id claim, or its sub claim when the token has no id. RBAC looks up roles by this id, and it owns the records the user creates unless mapUserToResourceId is set. See user IDs from JWT providers.

Constructor parameters

publishableKey?:

string

= process.env.CLERK_PUBLISHABLE_KEY

Your Clerk publishable key. Can be found in your Clerk Dashboard under API Keys.

secretKey?:

string

= process.env.CLERK_SECRET_KEY

Your Clerk secret key. Used for server-side authentication and token verification.

jwksUri?:

string

= process.env.CLERK_JWKS_URI

The JWKS URI from your Clerk application. Used to verify JWT signatures.

organizationId?:

string

= process.env.CLERK_ORGANIZATION_ID

Restrict login to members of a single Clerk organization, identified by its ID. Users who are not members of this organization are denied access.

organizationSlug?:

string

= process.env.CLERK_ORGANIZATION_SLUG

Restrict login to members of a single Clerk organization, identified by its slug. Users who are not members of this organization are denied access.

name?:

string

Custom name for the auth provider instance.

authorizeUser?:

(user: JwtPayload, request: MastraAuthRequest) => Promise<boolean> | boolean

Custom authorization function to determine if a user should be granted access. For token requests, user holds the verified Clerk JWT claims, identified by sub (JwtPayload is exported from @mastra/auth). When SSO is configured, requests authenticated by the SSO session cookie pass the session user instead, identified by id. Called after token verification. By default, allows all authenticated users, unless organizationId or organizationSlug is set, in which case only members of that organization are allowed.

Related

MastraAuthClerk Class