WorkOS

The @mastra/auth-workos package provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the auth option.

Prerequisites

This example uses WorkOS authentication. Make sure to:

1. Create a WorkOS account at workos.com
2. Set up an Application in your WorkOS Dashboard
3. Configure your redirect URIs and allowed origins
4. Set up Organizations and configure user roles as needed

.env

WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...

note

You can find your API key and Client ID in the WorkOS Dashboard under API Keys and Applications respectively.

For detailed setup instructions, refer to the WorkOS documentation for your specific platform.

Installation

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

npm

npm install @mastra/auth-workos@latest

pnpm

pnpm add @mastra/auth-workos@latest

Yarn

yarn add @mastra/auth-workos@latest

Bun

bun add @mastra/auth-workos@latest

Usage examples

Basic usage with environment variables

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthWorkos } from '@mastra/auth-workos'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos(),
  },
})

Custom configuration

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthWorkos } from '@mastra/auth-workos'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      apiKey: process.env.WORKOS_API_KEY,
      clientId: process.env.WORKOS_CLIENT_ID,
    }),
  },
})

Configuration

Default authorization

By default, MastraAuthWorkos grants access to any authenticated WorkOS user. The authorization check succeeds when the resolved user object contains both a Mastra user ID and a WorkOS user ID.

FGA membership loading

Set fetchMemberships: true when you use MastraFGAWorkos. This tells the auth provider to load the user's WorkOS organization memberships during authentication so FGA checks can resolve the correct organization membership ID.

src/mastra/auth.ts

import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos'

const workosAuth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  fetchMemberships: true,
})

const workosFga = new MastraFGAWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
})

When fetchMemberships is false, Mastra skips the extra WorkOS listOrganizationMemberships() call on each authenticated request.

Service tokens and custom JWT templates

For machine-to-machine or service-account access, you can configure MastraAuthWorkos to trust verified bearer-token claims from a WorkOS custom JWT template.

src/mastra/auth.ts

import { MastraAuthWorkos } from '@mastra/auth-workos'

const workosAuth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  redirectUri: process.env.WORKOS_REDIRECT_URI,
  trustJwtClaims: true,
  jwtClaims: {
    organizationId: 'org_id',
    organizationMembershipId: 'urn:mastra:organization_membership_id',
  },
})

This is useful when your JWT template already includes the exact FGA context Mastra needs, such as organizationMembershipId, tenant IDs, or service-principal identifiers. When trustJwtClaims is enabled, Mastra can fall back to those verified claims if a bearer token is not meant to round-trip through workos.userManagement.getUser().

Custom authorization

If you need stricter authorization, subclass MastraAuthWorkos and override authorizeUser():

src/mastra/auth.ts

import { MastraAuthWorkos } from '@mastra/auth-workos'
import type { HonoRequest } from 'hono'

class AdminOnlyWorkosAuth extends MastraAuthWorkos {
  async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
    return user?.metadata?.role === 'admin'
  }
}

const workosAuth = new AdminOnlyWorkosAuth({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
})

info

Visit MastraAuthWorkos for all available configuration options.

Client-side setup

When using WorkOS auth, you'll need to implement the WorkOS authentication flow to exchange an authorization code for an access token, then use that token with your Mastra requests.

Installing WorkOS SDK

First, install the WorkOS SDK in your application:

npm

npm install @workos-inc/node

pnpm

pnpm add @workos-inc/node

Yarn

yarn add @workos-inc/node

Bun

bun add @workos-inc/node

Exchanging code for access token

After users complete the WorkOS authentication flow and return with an authorization code, exchange it for an access token:

lib/auth.ts

import { WorkOS } from '@workos-inc/node'

const workos = new WorkOS(process.env.WORKOS_API_KEY)

export const authenticateWithWorkos = async (code: string, clientId: string) => {
  const authenticationResponse = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  })

  return authenticationResponse.accessToken
}

note

Refer to the WorkOS User Management documentation for more authentication methods and configuration options.

Configuring MastraClient

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

lib/mastra/mastra-client.ts

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

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

info

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 WorkOS access token, you can send authenticated requests:

React

src/api/agents.ts

import { WorkOS } from '@workos-inc/node'
import { MastraClient } from '@mastra/client-js'

const workos = new WorkOS(process.env.WORKOS_API_KEY)

export const callMastraWithWorkos = async (code: string, clientId: string) => {
  const authenticationResponse = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  })

  const token = authenticationResponse.accessToken

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

  const weatherAgent = mastra.getAgent('weatherAgent')
  const response = await weatherAgent.generate("What's the weather like in Nairobi")

  return response.text
}

cURL

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