# Authentification & Mind Keys

Synapse utilise deux méthodes d'authentification, chacune optimisée pour un cas
d'usage différent. Comprendre la différence est essentiel pour construire des
intégrations fiables.

## Deux méthodes d'auth

| Méthode | Cas d'usage | Limite de débit | Expiration |
|--------|----------|------------|--------|
| **Mind Key** | Agents LLM, outils automatisés | Aucune (en-tête) / 60 min (requête) | Jamais |
| **JWT** | Interface humaine, opérations de compte | Aucune | 7 jours |

## Mind Key (pour les agents)

Une Mind Key est un jeton d'API limité au tenant. Elle authentifie les données d'un
seul mind (mémoires, tâches, chat, scripts, etc.). Utilisez-la pour :

- Les agents LLM appelant l'API
- Les scripts d'automatisation en arrière-plan
- La configuration du serveur MCP
- Toute intégration longue durée

### Authentification par en-tête (recommandée)

```bash
curl -H "Authorization: Bearer mk_yourMindKeyHere" \
     https://synapse.schaefer.zone/memory/recall
```

### Paramètre de requête (pour les outils n'utilisant que des URLs)

```bash
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
```

> [!WARNING]
> Le paramètre de requête `?key=` est limité à **60 requêtes par minute**. L'en-tête
> Bearer n'a pas de limite de débit. Utilisez l'en-tête chaque fois que votre client
> prend en charge les en-têtes personnalisés.

### Créer une Mind Key

```bash
curl -X POST https://synapse.schaefer.zone/minds \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work Mind", "description": "Project memories"}'
```

La réponse inclut `mind_key` — **sauvegardez-la immédiatement**, elle n'est affichée
qu'une seule fois.

### Lister vos minds

```bash
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
```

### Supprimer un mind (irréversible !)

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds/m_xyz789
```

## JWT (pour les humains)

Les JWT authentifient le **compte utilisateur**, pas un mind spécifique. Utilisez-les
pour :

- L'inscription et la connexion au compte
- La création / liste / suppression de minds
- Le partage de minds avec d'autres utilisateurs
- La gestion des abonnements Web Push

### Inscription

```bash
curl -X POST https://synapse.schaefer.zone/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

Renvoie : `{ "jwt": "eyJ...", "user": {...} }`

### Connexion

```bash
curl -X POST https://synapse.schaefer.zone/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

Renvoie : `{ "jwt": "eyJ...", "user": {...} }`

### Expiration du JWT

Les JWT expirent après **7 jours**. Une fois expirés, appelez simplement `/login` à
nouveau pour en obtenir un nouveau. La Mind Key n'expire jamais, donc les intégrations
d'agents existantes continuent de fonctionner.

## Bonnes pratiques de sécurité

> [!CRITICAL]
> - **Ne commitez jamais de Mind Keys dans git.** Utilisez des variables d'environnement.
> - **Ne journalisez jamais de Mind Keys.** Masquez-les dans les logs (`mk_***...***xyz`).
> - **Pivotez les clés** si vous suspectez une fuite (supprimez le mind, créez-en un nouveau).
> - **Utilisez un mind par projet** pour limiter le rayon d'impact en cas de fuite de clé.

### Schéma de variable d'environnement

```bash
# .env (NE JAMAIS commiter ce fichier)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone
```

```typescript
// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});
```

### Configuration du serveur MCP

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}
```

## Schéma multi-mind

Chaque utilisateur peut avoir plusieurs minds. Schémas courants :

| Nom du mind | Rôle |
|-----------|---------|
| `work` | Mémoires liées au travail |
| `personal` | Préférences personnelles, famille |
| `project-synapse` | Contexte de projet spécifique |
| `learning-german` | Progression d'apprentissage |
| `assistant-default` | Fallback à usage général |

Utilisez différentes Mind Keys pour différentes sessions LLM afin de garder les
contextes isolés.

## Limites de débit

| Méthode d'auth | Limite | Portée |
|-------------|-------|-------|
| Mind Key (en-tête) | Aucune | Par mind |
| Mind Key (?key=) | 60/min | Par IP |
| JWT (en-tête) | Aucune | Par utilisateur |
| Endpoints publics | Aucune | Globale |

Les en-têtes de limite de débit (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,
`Retry-After`) sont inclus dans les réponses le cas échéant.

## Prochaines étapes

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — quand utiliser laquelle
- [API Memory](/docs/api/memory) — ce que vous pouvez faire avec une Mind Key
- [API User](/docs/api/user) — gestion de compte avec JWT