Clés API et journaux d'audit

ProcureSwift expose une API REST permettant aux systèmes tiers de lire et d'écrire des données d'approvisionnement par programmation. L'accès est contrôlé par des clés API — des secrets à longue durée de vie associés à un tenant, limités à des ressources spécifiques et soumis à une limitation du débit par minute. Chaque appel effectué avec une clé API est enregistré dans les journaux d'audit API afin que les administrateurs puissent voir exactement ce qui a été fait par quelle clé.

Où trouver ces fonctionnalités

• Clés API : menu principal → Clés API (/api-keys).
• Journaux d'audit API : menu principal → Journaux d'audit API (/api-audit-logs).

Ces deux pages nécessitent la permission ApiKeys / View. La création, la révocation et la suppression de clés requièrent respectivement ApiKeys / Create, ApiKeys / Manage et ApiKeys / Delete.

Créer une clé API

1. Ouvrez Clés API et cliquez sur Créer une clé API.
2. Remplissez le formulaire :
   • Nom — un libellé identifiant l'usage de cette clé (par exemple, Xero sync ou Internal data export). Obligatoire.
   • Périmètres (scopes) — cochez les ressources et les actions que cette clé est autorisée à effectuer. Laisser tout décoché accorde tous les scopes à la clé. Scopes disponibles :
     • purchase_orders:read, purchase_orders:write
     • invoices:read, invoices:write
     • catalog:read
     • delivery_notes:read, delivery_notes:write
     • quotations:read, quotations:write
     • proposals:read, proposals:write
     • rfqs:read, rfps:read
     • webhooks:manage
   • Expiration (facultatif) — date optionnelle après laquelle la clé cesse de fonctionner. Laisser vide pour une clé sans expiration.
   • Limite / min — nombre maximum de requêtes que cette clé peut effectuer par minute. La valeur par défaut est 100. La plage autorisée est de 1 à 10000.
3. Cliquez sur Créer.

Affichage unique du secret

Immédiatement après la création, la valeur complète de la clé API est affichée une seule fois dans une boîte de dialogue de confirmation. Copiez-la maintenant et stockez-la dans un gestionnaire de mots de passe ou un coffre-fort sécurisé — la plateforme ne l'affichera plus jamais. Si la clé est perdue, révoquez-la et créez-en une nouvelle.

La liste des clés n'affiche ensuite que le préfixe de la clé (les premiers caractères), ce qui permet de l'identifier dans les journaux sans révéler le secret complet.

Gérer les clés existantes

Le tableau Clés actives sur /api-keys affiche : Nom, Préfixe de la clé, Périmètres (scopes), Expire, État, Dernière utilisation, Limite de débit, Créé.

Actions disponibles par ligne :

• Révoquer (icône de blocage) — désactive immédiatement la clé. Les requêtes futures utilisant cette clé sont rejetées. Les clés révoquées restent dans la liste avec le statut Révoquée à des fins d'audit.
• Supprimer (icône de corbeille) — supprime définitivement l'enregistrement de la clé. Utilisez cette option pour nettoyer les clés révoquées une fois qu'elles ne figurent plus dans la fenêtre de rétention des journaux actifs.

Une clé ayant atteint sa date d'expiration est automatiquement inactive — la colonne Expire apparaît en rouge.

Utiliser une clé API

Transmettez la clé dans l'en-tête Authorization à chaque requête API :

Authorization: ApiKey <your-key>

Combiné avec l'identifiant du tenant dans l'en-tête tenant, cela suffit au serveur pour authentifier la requête et en délimiter la portée.

Journaux d'audit API

La page Journaux d'audit API enregistre chaque requête HTTP effectuée avec une clé API. Chaque ligne affiche :

• Clé API — nom de la clé utilisée.
• Méthode — méthode HTTP (GET / POST / PUT / DELETE), avec un code couleur.
• Chemin — l'endpoint appelé.
• État HTTP — code de statut HTTP, coloré par classe (2xx vert, 4xx orange, 5xx rouge).
• Adresse IP — l'adresse IP cliente de l'appel.
• Durée — durée de l'appel, en millisecondes.
• Horodatage — moment où l'appel a eu lieu.

Utilisez le menu déroulant Filtrer par clé API pour restreindre le journal à une seule clé.

Le journal est paginé (25 lignes par page par défaut) et trié du plus récent au plus ancien.

Conseils

• Créez une clé par intégration plutôt qu'une clé partagée pour tout — ainsi, révoquer une intégration compromise ne perturbe pas les autres.
• Définissez des scopes restreints. Un script d'export en lecture seule ne devrait obtenir que des scopes :read.
• Utilisez la limitation de débit pour protéger à la fois la plateforme et le système tiers. Un script mal configuré qui sollicite l'API en boucle serrée est beaucoup plus facile à diagnostiquer lorsqu'il reçoit 429 Too Many Requests plutôt que de faire tomber une dépendance.
• Consultez régulièrement le journal d'audit pour repérer des chemins inattendus ou des clusters de codes 4xx/5xx — ils signalent souvent une intégration nécessitant une maintenance.

Permissions

Action	Permission requise
Consulter les clés, consulter le journal d'audit	ApiKeys / View
Créer une nouvelle clé	ApiKeys / Create
Révoquer une clé	ApiKeys / Manage
Supprimer une clé	ApiKeys / Delete

Guides associés

• Webhooks — pour recevoir des notifications d'événements en temps réel depuis la plateforme.