> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# WorkOS

Le package `@mastra/auth-workos` fournit l'authentification WorkOS à Mastra. Il vérifie les requêtes entrantes à l'aide de jetons d'accès WorkOS et s'intègre au serveur Mastra grâce à l'option `auth`.

## Prérequis

Cet exemple utilise l'authentification WorkOS. Veillez à :

1. créer un compte WorkOS sur [workos.com](https://workos.com/) ;
2. configurer une application dans votre tableau de bord WorkOS ;
3. configurer vos URI de redirection et les origines autorisées ;
4. configurer des organisations et les rôles des utilisateurs selon vos besoins.

```env
WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...
```

> **Remarque:** Vous trouverez votre clé API et votre ID client dans le tableau de bord WorkOS, respectivement sous « API Keys » et « Applications ».
>
> Pour obtenir des instructions de configuration détaillées et adaptées à votre plateforme, consultez la [documentation de WorkOS](https://workos.com/docs).

## Installation

Avant d'utiliser la classe `MastraAuthWorkos`, vous devez installer le package `@mastra/auth-workos`.

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

## Exemples d'utilisation

### Utilisation de base avec des variables d'environnement

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

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

### Configuration personnalisée

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

### Autorisation par défaut

Par défaut, `MastraAuthWorkos` accorde l'accès à tout utilisateur WorkOS authentifié. La vérification de l'autorisation réussit lorsque l'objet utilisateur obtenu contient à la fois un ID utilisateur Mastra et un ID utilisateur WorkOS.

### Chargement des appartenances pour FGA

Définissez `fetchMemberships: true` lorsque vous utilisez [`MastraFGAWorkos`](https://mastra.zisheng.pro/fr/docs/server/auth/fga). Le Provider d'authentification charge alors les appartenances de l'utilisateur aux organisations WorkOS pendant l'authentification, afin que les vérifications FGA puissent déterminer l'ID d'appartenance à l'organisation approprié.

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

Lorsque `fetchMemberships` vaut `false`, Mastra n'effectue pas l'appel WorkOS supplémentaire à `listOrganizationMemberships()` pour chaque requête authentifiée.

### Jetons de service et modèles JWT personnalisés

Pour les accès machine à machine ou via un compte de service, vous pouvez configurer `MastraAuthWorkos` afin qu'il approuve les claims vérifiés d'un jeton porteur issus d'un modèle JWT WorkOS personnalisé.

```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',
  },
})
```

Cette option est utile lorsque votre modèle JWT contient déjà le contexte FGA précis dont Mastra a besoin, comme `organizationMembershipId`, des ID de locataire ou des identifiants de principal de service. Lorsque `trustJwtClaims` est activé, Mastra peut se rabattre sur ces claims vérifiés si un jeton porteur n'est pas destiné à effectuer un aller-retour via `workos.userManagement.getUser()`.

### Autorisation personnalisée

Si vous avez besoin d'une autorisation plus stricte, créez une sous-classe de `MastraAuthWorkos` et redéfinissez `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,
})
```

Consultez [MastraAuthWorkos](https://mastra.zisheng.pro/fr/reference/auth/workos) pour découvrir toutes les options de configuration disponibles.

## Configuration côté client

Lorsque vous utilisez l'authentification WorkOS, vous devez implémenter le flux d'authentification WorkOS afin d'échanger un code d'autorisation contre un jeton d'accès, puis utiliser ce jeton dans vos requêtes Mastra.

### Installer le SDK WorkOS

Commencez par installer le SDK WorkOS dans votre 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
```

### Échanger le code contre un jeton d'accès

Une fois que les utilisateurs ont terminé le flux d'authentification WorkOS et sont revenus avec un code d'autorisation, échangez ce code contre un jeton d'accès :

```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
}
```

> **Remarque:** Consultez la [documentation WorkOS User Management](https://workos.com/docs/authkit/vanilla/nodejs) pour découvrir d'autres méthodes d'authentification et options de configuration.

## Configurer `MastraClient`

Lorsque `auth` est activé, toutes les requêtes effectuées avec `MastraClient` doivent inclure un jeton d'accès WorkOS valide dans l'en-tête `Authorization` :

```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:** Le jeton d'accès doit être précédé de `Bearer` dans l'en-tête Authorization.
>
> Consultez le [SDK client Mastra](https://mastra.zisheng.pro/fr/docs/server/mastra-client) pour davantage d’options de configuration.

### Effectuer des requêtes authentifiées

Une fois `MastraClient` configuré avec le jeton d'accès WorkOS, vous pouvez envoyer des requêtes authentifiées :

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