@mastra/core/dist/docs/references/docs-server-auth-workos.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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](https://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](https://workos.com/docs) for your specific platform.

## Installation

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

**npm**:

```bash
npm install @mastra/auth-workos@latest
```

**pnpm**:

```bash
pnpm add @mastra/auth-workos@latest
```

**Yarn**:

```bash
yarn add @mastra/auth-workos@latest
```

**Bun**:

```bash
bun add @mastra/auth-workos@latest
```

## Usage examples

### Basic usage with environment variables

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

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

### Custom configuration

```typescript
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`](https://mastra.ai/docs/server/auth/fga). 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.

```typescript
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.

```typescript
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()`:

```typescript
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](https://mastra.ai/reference/auth/workos) 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**:

```bash
npm install @workos-inc/node
```

**pnpm**:

```bash
pnpm add @workos-inc/node
```

**Yarn**:

```bash
yarn add @workos-inc/node
```

**Bun**:

```bash
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:

```typescript
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](https://workos.com/docs/authkit/vanilla/nodejs) 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:

```typescript
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](https://mastra.ai/docs/server/mastra-client) for more configuration options.

### Making authenticated requests

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

**React**:

```typescript
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**:

```bash
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"
  }'
```