Clés d'API

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la capacité côté produit : guide produit ; l'appeler : guide développeur.

Pour une intégration connue - un partenaire, un batch, un serveur qui n'a pas d'utilisateur - et pas pour un agent (celui-ci reçoit un jeton OAuth, Agents et MCP). Une clé est liée à un tenant, à des opérations nommées et à une date de fin ; elle n'atteint jamais l'amont.

Commande - créer une clé :

docker run --rm -it ghcr.io/flexwiz/flexway:<version> api-key   # ou le binaire : flexway api-key

La commande demande l'identifiant, le tenant, les opérations et la durée (90 jours par défaut), puis affiche une seule fois la clé (fwk_ + 43 caractères, 256 bits aléatoires) et l'entrée à ajouter au magasin - son empreinte SHA-256, jamais la clé :

# api-keys.yaml - en grappe, un Secret synchronisé par ESO, monté en lecture seule
keys:
  - id: acme-billing-2026-10
    hash: sha256:9f2c...
    tenant: acme
    operations: [listInvoices, getInvoice]
    expires_at: 2027-01-01T00:00:00Z

La configuration nomme le magasin ; le contrat dit où une clé est acceptée, par une alternative apiKey à côté de celle du jeton :

# flexway.yaml
auth:
  api_keys: { store: "file:./api-keys.yaml" }

# contrat
components:
  securitySchemes:
    key: { type: apiKey, in: header, name: Authorization }   # toujours Authorization: ApiKey <clé>
paths:
  /invoices:
    get:
      operationId: listInvoices
      security: [ { customers: [invoices:read] }, { key: [] } ]   # un jeton, ou une clé liée

Vérif :

Appel	Réponse
Authorization: ApiKey <clé> sur une opération liée	relayé ; l'amont reçoit X-Tenant de la clé, sans la clé
Clé valide, opération qu'elle ne nomme pas	403
Clé sur une opération sans alternative apiKey	401, WWW-Authenticate: Bearer
Clé inconnue, expirée ou sans le préfixe fwk_	401, WWW-Authenticate: ApiKey ; le journal nomme la clé expirée par son id, jamais la clé
Clé dans un autre en-tête (X-Api-Key) ou dans l'URL	ignorée ; un schéma apiKey hors Authorization est refusé au chargement

Cycle de vie : le magasin est relu à chaque rechargement (Changer la configuration sans redémarrer). Émettre = ajouter une entrée ; révoquer = la retirer ; tourner = deux entrées le temps que l'intégration bascule, puis retirer l'ancienne. Une entrée qui nomme une opération qu'aucun contrat ne déclare est refusée au chargement, comme une politique. Le débit se compte par clé (apikey:<id>).