Référence API

API : Clés API

Créer et gérer les clés API qui authentifient vos applications. Chaque clé API peut avoir des permissions restreintes (moindre privilège) et une liste blanche d'IPs.

Méthode	Endpoint	Description
GET	/v1/api-keys	Lister les clés API
POST	/v1/api-keys	Créer une clé API
GET	/v1/api-keys/:id	Obtenir une clé API
PATCH	/v1/api-keys/:id	Modifier une clé API
DELETE	/v1/api-keys/:id	Révoquer une clé API

Créer une clé API

# Créer une clé API de production (mode enveloppe, IP restreinte)
curl -s -X POST https://api.mafate.io/v1/api-keys \
  -H "Authorization: Bearer $MAFATE_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "service-inscription-prod",
    "permissions": ["keys:wrap"],
    "allowed_ips": ["10.0.1.0/24", "10.0.2.5"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

# Réponse : le token n'est visible qu'une seule fois
{
  "id": "ak_01HXK9B2YZRPQ3VWMN4T5J6D7",
  "name": "service-inscription-prod",
  "prefix": "eaas_sk_EXEMPLE",
  "secret": "eaas_sk_EXEMPLE_NON_VALIDE",
  "permissions": ["keys:wrap"],
  "allowed_ips": ["10.0.1.0/24", "10.0.2.5"],
  "status": "active",
  "created_at": "2026-03-18T10:00:00Z",
  "expires_at": "2027-01-01T00:00:00Z"
}
# IMPORTANT: conservez le secret en lieu sûr, il ne sera plus affiché

Sécurité : restriction par IP

Le champ allowed_ips est optionnel mais fortement recommandé en production. Quand il est configuré, seules les requêtes provenant de ces IPs sont acceptées. Supporte les IPs exactes et les plages CIDR (ex : 10.0.0.0/8). Les requêtes depuis une IP non autorisée reçoivent un 403 Forbidden.

Permissions disponibles

Permission	Description
keys:wrap	Emballer ET désemballer une clé de données. C’est la permission du chemin nominal : en mode enveloppe, un service qui écrit et lit n’a besoin que de celle-ci.
encrypt	Chiffrer côté serveur, et calculer une empreinte avec /v1/hash. ⚠️ Le chiffrement serveur est refusé par défaut ; le hachage, lui, reste ouvert.
decrypt	Déchiffrer côté serveur. Refusé par défaut, comme encrypt.
keys:read	Lire les clés de chiffrement
keys:write	Créer, modifier et faire tourner des clés
keys:export	Exporter des clés (matériel cryptographique)
api_keys:read	Lister les clés API
api_keys:write	Créer, modifier et révoquer les clés API
audit:read	Lire les journaux d'audit

Principe de moindre privilège

Créez une clé API par service, avec les seules permissions dont ce service a besoin. En mode enveloppe, un service qui écrit et lit des champs chiffrés n’a besoin que de keys:wrap : ni encrypt, ni decrypt, ni keys:export.

API Audit