Authentication
Chaque requête vers l'API publique s'authentifie avec une clé API passée dans le header Authorization. Les clés ont des scopes (catalog vs knowledge, read vs write) et sont rattachées à une seule company. Pas de flow OAuth, pas de JWT, pas de signed requests, juste un bearer token par appel.
Réservé aux admins
Seuls les utilisateurs avec le rôle admin sur une company peuvent créer ou gérer des clés API. Si la page Developer Credentials de votre dashboard est en lecture seule, demandez au propriétaire de la company de vous accorder le rôle admin avant.
Générer une clé
- Ouvrez votre dashboard sur app.thehumind.com.
- Allez dans Settings → Developer → Credentials.
- Cliquez sur Create API key.
- Choisissez :
- Cliquez sur Create.
- Copiez immédiatement le secret. Il n'est affiché qu'une seule fois et ne sera plus jamais montré.
Affichage unique
La clé complète n'est affichée que dans la modale, juste après la création. Une fois la modale fermée, le dashboard ne stocke plus que le préfixe de la clé (hmd_live_xxxxx_…) et les métadonnées. Il n'y a pas de bouton « afficher la clé ». Si vous la perdez, vous devez la regenerer.
Après création, la nouvelle clé apparaît dans la liste avec son préfixe, son label, ses scopes, son environment et sa date de création. Vous pouvez la révoquer depuis là à tout moment.
Utiliser la clé
Envoyez la clé dans le header Authorization à chaque requête :
curl https://api.thehumind.com/public/v1/products \
-H "Authorization: Bearer hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a"C'est tout le contrat d'authentification. Pas de timestamp, pas de signature, pas de nonce. La connexion est HTTPS-only. Les requêtes en HTTP sont rejetées avant même d'atteindre l'API.
Traitez la clé comme un mot de passe
Ne committez jamais la clé dans un repo, ne la collez pas dans une capture d'écran, ne la loggez pas et ne l'envoyez pas en query string. Stockez-la dans le secret store de votre plateforme (GitHub Actions secrets, Vercel env, AWS Secrets Manager, etc.).
Format de clé
Une clé API Humind ressemble à :
hmd_live_aB3xK9qLm2pR7sT5wY8zN1_4f7c2e9a
└─┬─┘ └┬─┘ └────────┬────────┘ └───┬───┘
│ │ │ └──── Checksum CRC32 8 caractères (hex minuscule)
│ │ └─────────────────── Secret base62 22 caractères
│ └──────────────────────────────── Environment : `live` ou `test`
└───────────────────────────────────── Préfixe Humind (constant)| Segment | Description |
|---|---|
hmd_ | Préfixe Humind constant. Permet aux outils de secret-scanning (GitHub, GitGuardian, etc.) de détecter une clé fuitée d'un coup d'œil. |
live ou test | Environment. Doit correspondre à l'environment choisi à la création. Voir Test mode. |
| Secret base62 22 chars | L'entropie réelle (~131 bits). Généré côté serveur. |
| Checksum CRC32 8 chars | Valide le reste du token côté client et en bordure d'API. Une typo dans la partie secret est rejetée comme invalid_checksum avant tout lookup en base. |
Le format de token complet est hmd_(live|test)_[A-Za-z0-9]{22}_[a-f0-9]{8}.
Pourquoi un checksum ?
Le checksum permet de rejeter les clés malformées instantanément, sans aucun lookup en base. Ça veut aussi dire qu'une erreur de copier-coller (un caractère manquant, une lettre intervertie) échoue rapidement avec un invalid_checksum précis plutôt qu'un 401 générique.
Test mode
Le mode test est actuellement désactivé pour les nouvelles clés ; les clés test existantes continuent de s'authentifier. Les requêtes POST /companies/api-keys avec environment: "test" sont rejetées avec 400 test_mode_unavailable, et le dashboard ne propose plus le choix live/test à la création, donc toutes les nouvelles clés sont live. Le tableau ci-dessous décrit le modèle test-mode utilisé par les clés test créées avant la désactivation et le comportement attendu au retour de la fonctionnalité.
Les clés API existent en deux variantes : live et test. Le mode est inscrit dans le préfixe de la clé et ne peut pas être changé après création.
| Mode | Préfixe | Sur quoi ça touche |
|---|---|---|
live | hmd_live_… | Votre vrai catalogue, celui que voient vos clients. L'assistant utilise ces produits quand il répond aux acheteurs. |
test | hmd_test_… | Une surface de test isolée. Les ressources créées avec une clé test sont isolées du catalogue live. |
Utilisez test pour vos pipelines CI, scripts de régression, exploration et tout ce que vous ne voulez pas que les acheteurs voient. Les ressources test ne contaminent jamais le catalogue live : une clé live ne peut ni lire ni modifier des ressources test et vice versa.
Setup recommandé
- Une clé
livepar environnement de production (une dans votre CI, une dans votre backend prod, etc.) pour pouvoir les faire tourner indépendamment. - Une clé
testpour CI/staging que vous pouvez faire tourner agressivement sans coordination.
Scopes
Les scopes restreignent ce que chaque clé peut faire. Ils sont immuables après création, pour changer les scopes, créez une nouvelle clé et révoquez l'ancienne.
| Scope | Endpoints qui le requièrent | Quand l'accorder |
|---|---|---|
catalog:read | GET /products, GET /products/{id} | Accès catalogue read-only. Utile pour les scripts de vérification ou les outils back-office. |
catalog:write | POST /products, POST /products/batch, PUT /products/{id}, PATCH /products/{id}, DELETE /products/{id} | Pousser ou mettre à jour votre catalogue depuis votre backend e-commerce, un job ETL ou un script de migration. Inclut le read-on-write (vous récupérez l'objet réponse). |
knowledge:read | GET /knowledge, GET /knowledge/{id} | Lire FAQ, guides de tailles, policies. |
knowledge:write | POST /knowledge, POST /knowledge/batch, PUT /knowledge/{id}, PATCH /knowledge/{id}, DELETE /knowledge/{id} | Pousser FAQ et autre contenu free-form. |
Choisissez le set le plus étroit qui satisfait votre cas d'usage. Un script de migration qui ne fait que pousser des produits n'a pas besoin de knowledge:*.
Les scopes insuffisants renvoient 403
Si une requête atteint un endpoint pour lequel votre clé n'a pas le scope, l'API répond 403 Forbidden avec le code d'erreur insufficient_scope, et details.required et details.missing listent ce qui manque. Voir Errors.
Plusieurs clés
Vous pouvez avoir jusqu'à 10 clés actives par company simultanément. Le multi-clés est encouragé :
- Une clé par environnement (CI, staging, prod) : pour les faire tourner indépendamment.
- Une clé par intégration (votre backend, un ETL tiers, un outil de migration) : pour qu'une révocation n'en casse pas une autre.
- Une clé read-only à scope étroit pour les health checks, séparée de la clé
catalog:writeque votre backend utilise.
Les clés révoquées ne comptent pas dans la limite des 10 actives ; elles restent dans la liste comme audit trail.
Faire tourner une clé
Quand vous régénérez une clé depuis le dashboard, l'ancienne clé est révoquée immédiatement. La prochaine requête qui utilise l'ancienne clé reçoit 401 Unauthorized avec le code revoked — typiquement en quelques millisecondes, et au pire en 60 secondes dans le cas peu probable où un worker aurait un cache d'auth positif chaud pas encore invalidé.
Pour une rotation zero-downtime, ne régénérez pas. Faites plutôt :
- Créez une nouvelle clé avec les mêmes scopes et environment. Copiez son secret.
- Déployez la nouvelle clé dans le secret store de votre plateforme et redémarrez votre service.
- Vérifiez que le service utilise la nouvelle clé (regardez la colonne « Last used at » sur la nouvelle clé dans le dashboard, et confirmez que celle de l'ancienne clé n'avance plus).
- Révoquez l'ancienne clé depuis le dashboard.
C'est le même pattern que Stripe et GitHub. Le dashboard expose les timestamps « last used » pour que vous sachiez quand il est sûr de révoquer.
Regenerate est destructif
« Regenerate » remplace la clé en place : même label, mêmes scopes, mais un nouveau secret, et l'ancienne révoquée instantanément. Utilisez-le uniquement quand l'ancienne clé a déjà fuité ou ne fonctionne plus, jamais comme partie d'une rotation planifiée.
Si une clé fuite
Traitez toute clé fuitée comme compromise, même si vous ne l'avez vue que dans un log privé ou un DM Slack :
- Révoquez-la immédiatement depuis le dashboard. La révocation atteint l'edge de l'API en 60 secondes maximum, après quoi toute requête avec cette clé échoue en
401 / revoked. - Créez une nouvelle clé et mettez à jour votre secret store.
- Auditez vos logs d'usage. Le dashboard enregistre l'IP et le user-agent de la dernière requête par clé. Si quelque chose vous semble bizarre (une IP que vous ne reconnaissez pas, du trafic en dehors de vos heures habituelles), signalez-le au support.
Vecteurs de fuite courants à surveiller :
- Committée dans un repo public ou privé.
- Collée dans une issue Notion / Linear / GitHub.
- Loggée par un client HTTP qui imprime les headers en cas d'erreur.
- Envoyée en query string (à ne pas faire ; les query strings finissent dans les access logs CDN et l'historique navigateur).
GitHub secret scanning
Le secret scanning automatique de GitHub reconnaît les préfixes hmd_live_ et hmd_test_ et nous notifie quand une clé est committée dans un repo GitHub public. La notification atteint notre équipe sécurité en quelques minutes et nous vous contacterons pour coordonner.
Pour aller plus loin
- Conventions : format des requêtes, identifiants, idempotency.
- Errors : codes d'erreur liés à l'auth (
missing_credentials,invalid_checksum,revoked,insufficient_scope, …). - Products : pousser votre premier produit.