Documentation / Concepts / Authentification

Authentification

Trois façons de se connecter, toutes rattachées à votre compte : la connexion OAuth pour les assistants (claude.ai, ChatGPT…), une clé API pour le code et l'API REST, ou une URL de connecteur secrète en dernier recours.

Quelle méthode choisir ?

Méthode	Pour	Donne accès à	Révocation
Connexion OAuth	claude.ai (web, mobile, Cowork), ChatGPT, Claude Code, tout client MCP distant compatible	Serveur MCP uniquement (`/mcp`)	Dashboard → Applications connectées, effet à l'appel suivant
Clé API `normi_…`	API REST, scripts, CI, paquet STDIO `@normi/mcp-dvf`, Cursor	API REST et serveur MCP	Créer une nouvelle clé révoque l'ancienne
URL de connecteur	Clients sans OAuth ni en-têtes personnalisés	Serveur MCP uniquement	Dashboard → Tokens, révocable à tout moment

Les crédits viennent toujours de votre clé active

Quelle que soit la méthode, chaque appel est débité sur la clé API active de votre compte. Une connexion OAuth n'a pas de solde propre : elle suit votre clé, y compris après une rotation.

Connexion OAuth (serveur MCP)

Collez https://mcp.normi.fr/mcp dans votre client, connectez-vous à Normi, puis autorisez l'application. Aucune clé à copier. Voir les guides Claude et ChatGPT.

Première autorisation : si votre compte n'a pas encore de clé API, une clé gratuite (500 crédits) est créée à ce moment-là, après une vérification anti-robot. Un compte qui a déjà une clé garde son solde et son plan.
Rotation : créer une nouvelle clé dans le dashboard ne déconnecte pas vos applications ; elles utilisent la nouvelle clé dès l'appel suivant.
Clé révoquée sans remplaçante : les appels échouent avec 403 no_active_key. Normi ne recrée jamais de clé à votre insu ; créez-en une et l'application reprend.
Durée de vie : le jeton d'accès expire au bout d'une heure et le client le renouvelle lui-même. Se déconnecter de normi.fr ne déconnecte pas vos applications.
Portée : un jeton OAuth ne fonctionne que sur le serveur MCP. L'API REST /v1 exige une clé API.

Claude Code

claude mcp add --transport http normi https://mcp.normi.fr/mcp
# puis, dans Claude Code :
/mcp

Pour les développeurs de clients MCP

Un appel sans identifiant renvoie 401 avec un en-tête WWW-Authenticate qui pointe vers les métadonnées de ressource protégée (RFC 9728). Elles désignent le serveur d'autorisation, qui prend en charge l'enregistrement dynamique des clients (RFC 7591), le flux authorization code avec PKCE (S256) et le jeton de rafraîchissement.

$ curl -i -X POST https://mcp.normi.fr/mcp
HTTP/2 401
www-authenticate: Bearer resource_metadata="https://mcp.normi.fr/.well-known/oauth-protected-resource/mcp"

Clé API : headers acceptés

Header	Usage recommandé	Exemple
`X-API-Key`	API REST (préféré)	`X-API-Key: normi_abc123`
`Authorization`	Clients MCP (Bearer standard)	`Authorization: Bearer normi_abc123`

Les deux headers sont acceptés sur l'API REST et le serveur MCP. Pour les intégrations REST classiques, utilisez X-API-Key.

Exemples

curl "https://mcp.normi.fr/v1/transactions?code_postal=75011" \
  -H "X-API-Key: normi_votre_token"

# Alternativement — Authorization: Bearer (aussi accepté en REST)
curl "https://mcp.normi.fr/v1/transactions?code_postal=75011" \
  -H "Authorization: Bearer normi_votre_token"

Configuration MCP (Claude Desktop)

{
  "mcpServers": {
    "normi": {
      "command": "npx",
      "args": ["-y", "@normi/mcp-dvf"],
      "env": {
        "NORMI_API_KEY": "normi_votre_token"
      }
    }
  }
}

Format du token

Les tokens Normi ont le format suivant :

normi_<base64url(32 octets aléatoires)>

Le préfixe normi_ permet d'identifier rapidement un token Normi dans vos logs et de le différencier d'autres secrets.

Le token brut n'est affiché qu'une seule fois

À la création, le token est affiché en clair une unique fois. Seul son hash SHA-256 est stocké côté serveur. Si vous le perdez, vous devrez créer un nouveau token (l'ancien sera révoqué et vos crédits transférés).

Rotation de token

Créer un nouveau token dans le dashboard révoque automatiquement et atomiquement tous vos tokens précédents. Le solde de crédits est transféré vers le nouveau token — vous ne recevez pas un nouveau lot de 500 crédits gratuits.

Un seul token actif par compte à tout moment
Les applications connectées en OAuth suivent automatiquement le nouveau token
La révocation est immédiate — les requêtes en cours avec l'ancien token échoueront avec HTTP 401
Toutes les données liées au token (alertes, portefeuille) restent accessibles avec le nouveau token

Bonnes pratiques de sécurité

Ne commitez jamais votre token dans un dépôt Git. Utilisez des variables d'environnement.
Côté serveur, stockez le token dans une variable d'environnement (ex. NORMI_API_KEY). Ne l'exposez jamais dans le code frontend.
Si votre token est compromis, créez-en un nouveau immédiatement depuis le dashboard. L'ancien est révoqué instantanément.
La vérification côté serveur utilise une comparaison en temps constant (résistante aux timing attacks).

Pagination

Filtres de localisation