Gestion des cles API
Les cles API permettent l'acces programmatique a SmartDoc sans necessiter de session utilisateur interactive. Chaque cle est liee a un tenant et peut etre restreinte par portee (scope) et par compagnie.
Creer une cle API
- Allez dans SmartDoc > Parametres > onglet API Keys
- Cliquez sur Create API Key
- Remplissez le formulaire :
| Champ | Description |
|---|---|
| Name | Nom descriptif de la cle (ex : « Claude Desktop — Production ») |
| Scope | Niveau d'acces : read-only, read-write ou full-access |
| Company Filter | Restriction optionnelle par compagnie (voir ci-dessous) |
| Expires At | Date d'expiration optionnelle |
- Cliquez Create
- Copiez la cle immediatement — elle ne sera plus jamais affichee
La cle complete (sk-smartdoc-...) est affichee uniquement au moment de la creation. Copiez-la et stockez-la dans un endroit securise. Si vous la perdez, vous devrez creer une nouvelle cle.
Portees (Scopes)
Les portees definissent ce qu'une cle peut faire :
| Portee | Lecture | Ecriture | Suppression | Revelation secrets |
|---|---|---|---|---|
| read-only | Oui | Non | Non | Non |
| read-write | Oui | Oui | Non | Non |
| full-access | Oui | Oui | Oui | Oui |
Recommandations
- read-only : Pour les outils d'IA (Claude, Cursor) qui consultent la documentation
- read-write : Pour les scripts d'automatisation qui creent/modifient des entries
- full-access : Uniquement pour les administrateurs — permet de supprimer des donnees et reveler les mots de passe
Filtrage par compagnie
Vous pouvez restreindre l'acces d'une cle a certaines compagnies clientes :
| Mode | Description |
|---|---|
| All | Acces a toutes les compagnies du tenant (defaut) |
| Include | Acces uniquement aux compagnies selectionnees |
| Exclude | Acces a toutes les compagnies sauf celles selectionnees |
Cela est utile pour creer des cles limitees a un seul client, ou pour exclure des donnees sensibles.
Format de la cle
Les cles SmartDoc suivent le format :
sk-smartdoc-a1b2c3d4e5f6...
- Prefixe
sk-smartdoc-pour identification rapide - 48 caracteres hexadecimaux aleatoires
- Longueur totale : ~60 caracteres
Revoquer une cle
- Dans l'onglet API Keys, trouvez la cle a revoquer
- Cliquez sur le bouton Revoke (icone poubelle)
- Confirmez la revocation
La revocation est permanente. Toutes les requetes utilisant cette cle recevront une erreur 401 Unauthorized immediatement.
Tableau de bord des cles
L'onglet API Keys affiche pour chaque cle :
| Colonne | Description |
|---|---|
| Name | Nom de la cle |
| Key | Prefixe + 4 derniers caracteres (ex : sk-smartdoc-...a1b2) |
| Scope | Badge de portee (read-only, read-write, full-access) |
| Company Filter | Mode de filtrage actif |
| Created | Date de creation |
| Last Used | Derniere utilisation |
| Requests | Nombre total de requetes effectuees |
| Status | Actif, Revoque ou Expire |
Securite
Double hachage
Chaque cle est protegee par deux algorithmes de hachage :
- SHA-256 — Pour la recherche rapide en base de donnees et en cache Redis
- bcrypt (12 rounds) — Pour la verification cryptographique securisee
La cle en clair n'est jamais stockee.
Rate limiting
Chaque cle est limitee a 1 000 requetes par heure. Les en-tetes de reponse indiquent l'etat :
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
En cas de depassement, l'API retourne 429 Too Many Requests avec un en-tete Retry-After: 3600.
Cache Redis
Les cles sont mises en cache Redis pendant 5 minutes pour des performances optimales. La revocation invalide immediatement le cache.
Journalisation
Toutes les operations d'ecriture (creation, modification, suppression) effectuees via l'API sont journalisees dans le journal d'audit SmartDoc avec :
- L'identifiant de la cle API
- L'adresse IP source
- Le type d'action
- L'entite et l'enregistrement affectes
Permissions requises
Seuls les utilisateurs avec le role SMARTDOC_ADMIN (ou superieur) peuvent creer et gerer les cles API.