Skip to main content

MastraAuthWorkos Class

The MastraAuthWorkos class provides authentication for Mastra using WorkOS. It verifies incoming requests using WorkOS access tokens and integrates with the Mastra server using the experimental_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 install @mastra/auth-workos@latest

Usage examples​

Basic usage with environment variables​

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { MastraAuthWorkos } from "@mastra/auth-workos";

export const mastra = new Mastra({
  // ..
  server: {
    experimental_auth: new MastraAuthWorkos(),
  },
});

Custom configuration​

src/mastra/index.ts
import { Mastra } from "@mastra/core/mastra";
import { MastraAuthWorkos } from "@mastra/auth-workos";

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

Configuration​

User Authorization​

By default, MastraAuthWorkos checks whether the authenticated user has an 'admin' role in any of their organization memberships. The authorization process:

  1. Retrieves the user's organization memberships using their user ID
  2. Extracts all roles from their memberships
  3. Checks if any role has the slug 'admin'
  4. Grants access only if the user has admin role in at least one organization

To customize user authorization, provide a custom authorizeUser function:

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,
  authorizeUser: async (user) => {
    return !!user;
  },
});

See the MastraAuthWorkos API reference 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 install @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;
};

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

Configuring MastraClient​

When experimental_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}`,
    },
  });
};

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

See Mastra Client SDK for more configuration options.

Making authenticated requests​

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

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({
    messages: "What's the weather like in Nairobi",
  });

  return response.text;
};