# Authentification et clés

> Authentifiez-vous avec des clés d’API Bearer. Clés Live et clés de test, ce que renvoie le mode Test, révocation d’une clé et limite de dépense mensuelle par clé.

Source : https://fileverity.com/fr/docs/authentication

Chaque requête nécessite une clé d’API, envoyée comme jeton Bearer dans l’en-tête `Authorization`.

**Requête authentifiée: cURL**

```bash
curl https://api.fileverity.com/v1/models \
  -H "Authorization: Bearer $FILEVERITY_API_KEY"
```

**Requête authentifiée: JavaScript**

```javascript
const response = await fetch("https://api.fileverity.com/v1/models", {
  headers: { Authorization: "Bearer " + process.env.FILEVERITY_API_KEY },
});
```

**Requête authentifiée: Python**

```python
import os
import requests

requests.get("https://api.fileverity.com/v1/models", headers={"Authorization": "Bearer " + os.environ["FILEVERITY_API_KEY"]})
```

Les clés sont des secrets. Appelez l’API depuis votre serveur, stockez les clés dans des variables d’environnement ou un gestionnaire de secrets, et ne les placez jamais dans du code exécuté dans le navigateur ni dans des applications mobiles.

## Clés Live et clés de test

Une clé est formée de `fv_live_` ou `fv_test_`, suivi de 40 lettres et chiffres. Le préfixe détermine le mode.

|  | Clé Live | Clé de test |
| --- | --- | --- |
| Préfixe | `fv_live_...` | `fv_test_...` |
| Exécute les modèles | Oui | Non |
| Facturé sur votre solde ou votre démarrage gratuit | Oui | Jamais |
| Résultats | Réels | Exemples fixes |
| `livemode` dans les réponses | `true` | `false` |
| Webhooks | Envoyés | Non envoyés |

Les deux modes partagent un même espace de travail. Ils utilisent les mêmes points d’accès, la même validation, les mêmes limites de débit et les mêmes codes d’erreur : vous pouvez donc développer avec une clé de test, puis changer de clé pour passer en production.

## Comportement du mode Test

- **Détections de texte.** La requête est validée comme avec une clé Live : les contrôles de longueur minimale, de longueur maximale et de langue s’appliquent toujours. La réponse est un résultat `human` fixe, avec `score` et `ai_fraction` égaux à `0` et sans `segments`. `usage` est calculé à partir de votre texte. Rien n’est facturé ni enregistré.
- **Fichiers.** Les téléversements sont validés, mais les octets ne sont pas conservés, et une requête de téléversement JSON renvoie un objet de téléversement de test au lieu d’une véritable URL présignée (`upload.test` vaut `true`), avec le fichier déjà à l’état `uploaded`. Les fichiers sont séparés par mode : une clé de test ne peut pas lire les fichiers Live, et une clé Live ne peut pas lire les fichiers de test.
- **Créer une analyse.** Renvoie immédiatement `200` avec `status: succeeded`, un exemple fixe de niveau `L2` et d’action `accept`, et `livemode: false`. L’ID d’analyse commence par `an_test` et reste le même pour un même fichier. L’ID de rapport commence par `FV-TEST-` et n’a pas de page de vérification publique. Le rapport d’exemple ne contient que les champs présents dans l’exemple.
- **Récupérer une analyse.** Ne fonctionne qu’avec les ID d’analyses d’exemple. **Lister les analyses** renvoie toujours une liste vide, **annuler** renvoie `not_cancelable`, et il n’existe pas de PDF d’exemple. Les clés de test ne peuvent pas lire les analyses Live ni les PDF de rapport Live.

**Exemple de détection de texte, clé de test**

```json
{
  "id": "tdet_Qm4vB7nP1sK8tL3wR6yZ2cXa",
  "object": "text.detection",
  "created": 1793664000,
  "model": "fvdoc-3-text-2026-11-03",
  "livemode": false,
  "language": "en",
  "verdict": "human",
  "score": 0,
  "ai_fraction": 0,
  "segments": [],
  "usage": {
    "characters": 1412,
    "free_characters": 0,
    "billed_units": 2
  }
}
```

## Créer et révoquer des clés

Gérez les clés dans la Console, sous **Clés API**.

- **Créer.** Nommez la clé et choisissez son mode. La clé complète n’est affichée qu’une seule fois. Fileverity ne conserve qu’un hachage SHA-256 et les quatre derniers caractères : une clé perdue ne peut donc pas être récupérée, il faut en créer une nouvelle.
- **Limite.** Un espace de travail peut contenir jusqu’à 20 clés actives. Au-delà, la création d’une clé échoue avec `key_limit`.
- **Dernière utilisation.** La Console indique quand chaque clé a effectué sa dernière requête.
- **Révoquer.** Les requêtes qui utilisent une clé révoquée échouent immédiatement avec `invalid_api_key`.
- **Départ d’un membre.** Lorsqu’un membre quitte l’espace de travail ou en est retiré, les clés qu’il a créées sont révoquées. Créez les clés de production depuis un compte qui reste dans l’espace de travail.

### En cas de fuite d’une clé

1. Créez une nouvelle clé.
2. Mettez à jour vos logiciels pour qu’ils l’utilisent.
3. Révoquez l’ancienne clé.

## Limites de dépense mensuelles

Chaque clé peut avoir sa propre limite de dépense mensuelle, en dollars américains entiers. Seuls les propriétaires et les administrateurs de l’espace de travail peuvent la définir ou la modifier, à la création de la clé ou plus tard avec **Modifier la limite**. Une clé sans limite n’est bornée que par votre solde.

- La limite compte ce que la clé a dépensé durant le mois civil en cours (UTC) et se réinitialise le 1er du mois.
- Une requête qui ferait dépasser sa limite à la clé est rejetée avec `spend_limit_reached` (HTTP 402) avant tout traitement, et n’est pas facturée.
- Les vérifications du démarrage gratuit ne coûtent rien et ne comptent pas. Les vérifications échouées ou annulées ne sont pas facturées et ne comptent pas.
- Les limites s’appliquent aux clés Live. Les clés de test ne dépensent jamais.

> **Remarque.** Utilisez une clé distincte, avec sa propre limite, pour chaque service ou environnement. Une tâche qui s’emballe ne peut alors pas dépenser plus que la limite de cette clé.

## Erreurs d’authentification

| Code | Statut | Signification |
| --- | --- | --- |
| `missing_api_key` | 401 | Aucun en-tête `Authorization: Bearer` n’a été envoyé. |
| `invalid_api_key` | 401 | La clé est mal formée, inconnue ou révoquée. |
| `spend_limit_reached` | 402 | La clé a atteint sa limite de dépense mensuelle. |

Voir [Erreurs](https://fileverity.com/fr/docs/errors.md) pour la liste complète.