Authentification
Chaque requête, à l'exception du contrôle de santé, porte une clé. Les clés identifient une organisation plutôt qu'un utilisateur, et portent l'offre et le quota de cette organisation.
L'en-tête
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "X-API-Key: sk_live_9f21c4a70b8e…"
# Authorization: Bearer fonctionne aussi, pour les clients à qui cela facilite la vie.
curl -sS "https://api.skautik.com/v1/api/properties?city=Berlin" \
-H "Authorization: Bearer sk_live_9f21c4a70b8e…"L'un ou l'autre en-tête fonctionne. Si les deux sont présents, X-API-Key l'emporte. Un en-tête absent ou
mal formé renvoie 401 avec le code authentication_required, et la
réponse ne dit jamais si la clé n'existe pas ou a été révoquée :
faire la distinction permettrait de sonder l'existence de clés valides.
Types de clé
| Préfixe | Type | Ce qu'elle fait |
|---|---|---|
sk_live_ | Production | Lit et écrit l'inventaire réel. Limitée en débit sur le quota de votre offre. |
sk_test_ | Test | Lit un petit jeu de données fixe et accepte des écritures qui sont jetées. Gratuite, et généreusement limitée, pour que les tests d'intégration ne consomment pas de quota. |
Le préfixe fait partie de la clé : une chaîne qui fuit est donc reconnaissable comme un identifiant Skautik dans un journal ou lors d'un scan de dépôt. C'est délibéré : les scanners de secrets peuvent la détecter et vous alerter avant que quelqu'un d'autre ne la trouve.
Portées
Les portées sont par ressource plutôt qu'une paire globale lecture/écriture. Une clé est créée avec l'ensemble dont elle a besoin, et l'API refuse tout appel dont la clé n'a pas la portée exigée par cette route.
Accordez l'ensemble le plus étroit qui fasse le travail. Une clé émise pour l'analyse de marché ne peut ensuite ni lire les coordonnées de qui que ce soit ni retirer une annonce, quelle que soit la gravité d'une fuite.
| Portée | Permet |
|---|---|
properties:read | Lire les biens et leurs médias. |
properties:write | Créer, mettre à jour et retirer des biens. |
markets:read | Lire les statistiques et l'intelligence de marché. |
imports:write | Soumettre et gérer des imports en masse. |
exports:create | Demander des exports et en télécharger les résultats. |
images:write | Générer et attacher des images rendues. |
webhooks:manage | Créer, mettre à jour et supprimer des endpoints de webhook. |
inquiries:read | Lire les demandes déposées sur vos biens. |
Rotation
Les clés n'expirent pas selon un calendrier, car une expiration forcée tend à produire une panne plutôt qu'une meilleure sécurité. Faites plutôt une rotation délibérée. Une organisation peut détenir plusieurs clés à la fois précisément pour que cela ne demande aucune interruption :
- Créez une seconde clé à côté de celle en service.
- Déployez-la sur vos services et vérifiez que le trafic est bien passé dessus.
- Vérifiez sur la page des clés que l'ancienne s'est tue, plutôt que de le supposer.
- Révoquez l'ancienne clé.
La révocation prend effet immédiatement, sans délai de grâce.
Garder une clé secrète
- Côté serveur uniquement. Une clé livrée dans un navigateur ou un binaire mobile est une clé publiée, quelle que soit l'obfuscation. Passez par votre propre backend.
- Gardez les clés dans des variables d'environnement ou un gestionnaire de secrets, jamais dans un dépôt, un artefact de build ou un bundle client.
- Utilisez une clé distincte par environnement et par service, pour qu'en révoquer une ne fasse pas tout tomber avec elle.
- La clé complète est affichée une seule fois à la création et n'est stockée que sous forme de hachage. Nous ne pouvons pas vous la récupérer ; créez-en une nouvelle.
Si une clé fuit
Révoquez-la d'abord et enquêtez ensuite : une clé révoquée vous coûte un déploiement, une clé fuitée et active vous coûte votre quota et vos données.
Écrivez ensuite à security@skautik.com pour que nous puissions vérifier un usage que vous n'auriez pas fait. Nous surveillons aussi les hébergeurs de code publics pour nos préfixes de clé et révoquerons une clé trouvée exposée, en vous en informant.
Vérifier une clé
GET /v1/api/me indique l'organisation, l'offre et le quota restant derrière une
clé. C'est le bon appel pour un contrôle au démarrage ou une sonde de santé, car il
prouve que la clé fonctionne sans paginer une ressource.
Gérez les clés depuis la page des clés d'API.