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

# Better Auth

Le package `@mastra/auth-better-auth` fournit l'authentification Better Auth à Mastra. Il vérifie les requêtes entrantes au moyen de votre instance Better Auth et s'intègre au serveur Mastra via l'option `server.auth`.

## Prérequis

Cet exemple utilise Better Auth. Vérifiez que votre instance Better Auth est configurée et que vos variables d'environnement sont définies.

```env
# Required by Better Auth
BETTER_AUTH_SECRET=...   # at least 32 chars
BETTER_AUTH_URL=http://localhost:3000

# Example DB URL used by the snippet below (adjust for your setup)
DATABASE_URL=postgres://...
```

> **Remarque:** Pour des raisons de sécurité et de stabilité, Better Auth recommande de définir explicitement `baseURL` (ou de le faire au moyen de `BETTER_AUTH_URL`).

Si vous n'avez pas encore monté le gestionnaire de Better Auth afin que votre application puisse connecter les utilisateurs et créer des sessions, suivez le [guide d'installation de Better Auth](https://www.better-auth.com/docs/installation) pour monter la route `/api/auth/*` (ou le chemin de base que vous avez configuré).

## Installation

Installez le package `@mastra/auth-better-auth` :

**npm**:

```bash
npm install @mastra/auth-better-auth
```

**pnpm**:

```bash
pnpm add @mastra/auth-better-auth
```

**Yarn**:

```bash
yarn add @mastra/auth-better-auth
```

**Bun**:

```bash
bun add @mastra/auth-better-auth
```

## Exemple d'utilisation

Commencez par créer votre instance Better Auth :

```ts
import { betterAuth } from 'better-auth'

export const auth = betterAuth({
  database: {
    provider: 'postgresql',
    url: process.env.DATABASE_URL!,
  },
  emailAndPassword: {
    enabled: true,
  },
  baseURL: process.env.BETTER_AUTH_URL,
  secret: process.env.BETTER_AUTH_SECRET,
})
```

Utilisez-la ensuite avec Mastra :

```ts
import { Mastra } from '@mastra/core'
import { MastraAuthBetterAuth } from '@mastra/auth-better-auth'
import { auth } from '@/lib/auth'

const mastraAuth = new MastraAuthBetterAuth({
  auth,
})

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

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

## Autorisation personnalisée

```ts
const mastraAuth = new MastraAuthBetterAuth({
  auth,
  async authorizeUser(user) {
    // Example: only allow verified emails
    return user?.user?.emailVerified === true
  },
})
```

## Configuration des routes

```ts
const mastraAuth = new MastraAuthBetterAuth({
  auth,
  public: ['/health', '/api/status'],
  protected: ['/api/*', '/admin/*'],
})
```

### Règles de correspondance

- `public` et `protected` acceptent des chemins exacts, des motifs avec caractères génériques (comme `/api/*`) et des paramètres de chemin (comme `/users/:id`).
- Pour définir des règles propres à une méthode, utilisez des tuples comme `["/api/agents", ["GET", "POST"]]`.
- Si une route correspond à la fois à `public` et à `protected`, `public` l'emporte et aucune authentification n'est requise.
- Si aucune règle ne correspond, les routes sont considérées comme protégées par défaut, sauf si une route porte explicitement le marqueur `requiresAuth: false`.

## Configuration côté client

Lorsque l'authentification est activée, les requêtes adressées aux routes intégrées de Mastra doivent être authentifiées. En pratique, votre client doit donc envoyer l'identifiant utilisé par votre configuration Better Auth pour les requêtes authentifiées.

### Session par cookie (recommandé)

Si votre configuration Better Auth utilise des cookies, configurez le client pour qu'il envoie les identifiants. Pour les requêtes interorigines (par exemple Next.js sur `:3000` appelant Mastra sur `:4111`), activez la transmission des identifiants CORS sur le serveur Mastra :

```ts
export const mastra = new Mastra({
  server: {
    auth: mastraAuth,
    cors: {
      origin: 'http://localhost:3000', // your frontend origin
      credentials: true,
    },
  },
})
```

Configurez ensuite le client pour inclure les identifiants :

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

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})
```

Si vous appelez directement l'API, incluez également les identifiants dans `fetch` :

```ts
await fetch('http://localhost:4111/api/agents/weatherAgent/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({ messages: 'Weather in London' }),
})
```

### Jeton Bearer

Vous pouvez transmettre le jeton de session signé comme jeton Bearer. Récupérez-le depuis la session de votre client Better Auth et incluez-le dans l'en-tête `Authorization` :

```ts
import { MastraClient } from '@mastra/client-js'
import { authClient } from './auth-client' // your Better Auth client

const session = await authClient.getSession()

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  headers: {
    Authorization: `Bearer ${session.data?.session.token}`,
  },
})
```

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

**React**:

```tsx
import { mastraClient } from '../lib/mastra-client'

export const TestAgent = () => {
  async function handleClick() {
    const agent = mastraClient.getAgent('weatherAgent')

    const response = await agent.generate('Weather in London')

    console.log(response)
  }

  return <button onClick={handleClick}>Test Agent</button>
}
```

**cURL**:

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

## Dépannage

- **Réponse 401 à chaque requête** : vérifiez que le gestionnaire Better Auth est monté et que votre application peut créer une session valide. Assurez-vous que le client envoie soit un cookie de session, soit un en-tête `Authorization: Bearer <signed-token>`.
- **Cookies non envoyés entre origines** : définissez `credentials: "include"` dans `MastraClient`, puis configurez `server.cors` avec l'origine de votre frontend et `credentials: true`.
- **Jeton Bearer rejeté** : veillez à transmettre le jeton de session signé complet, obtenu depuis `authClient.getSession()`, et non un jeton brut ou non signé.
- **Problèmes d'URL de base** : définissez `baseURL` dans `betterAuth({ ... })` ou définissez `BETTER_AUTH_URL`.
- **Erreurs de connexion à la base de données** : vérifiez `DATABASE_URL` et la configuration du Provider de base de données.