Référence API

Vue d'ensemble de l'API

L'API MAFATE est une API REST JSON, versionnée et accessible via HTTPS. Toutes les requêtes requièrent une authentification par clé API.

URL de base

https://api.mafate.io/v1

Authentification

Toutes les requêtes doivent inclure votre clé API dans l'en-tête Authorization :

Authorization: Bearer eaas_sk_EXEMPLE_NON_VALIDE

Les requêtes sans clé API valide retournent un statut 401. Le préfixe est eaas_sk_ : le serveur n’a aucune notion d’environnement, il n’existe donc ni clé « live » ni clé « test ». Une clé de test est une clé ordinaire émise sur un locataire de test.

Format des réponses

Toutes les réponses sont au format JSON. Les réponses de succès contiennent les données directement :

// Succès
{
  "ciphertext": "AQIDAHj...",
  "wrapped_key": "CiQAe...",
  "iv": "9xK2mQ==",
  "key_id": "production-users",
  "key_version": 3
}

// Erreur : RFC 7807 (application/problem+json)
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "key not found"
}

Codes d'erreur HTTP

Status	title	Description
400	Bad Request	Corps invalide : JSON malformé, champ requis absent, base64 non conforme, DEK qui ne fait pas 32 octets
401	Unauthorized	Clé API absente, inconnue, expirée ou révoquée
403	Forbidden	La clé API n’a pas la permission requise, ou le wrapped_key présenté n’est pas authentifiable pour cette clé
403	Forbidden (E_ENVELOPE_ONLY)	Le locataire est en mode enveloppe, défaut de tout compte créé depuis le 11/08/2026 : /v1/encrypt et /v1/decrypt sont refusés. Chiffrez localement.
404	Not Found	Clé introuvable pour ce locataire. Rappel : le chemin attend l’UUID, pas le nom.
409	Conflict	Nom déjà pris, ou opération refusée par l’état de la clé (seule une clé active peut tourner ou emballer)
422	Decryption Failed	Le déchiffrement a échoué : chiffré altéré, mauvaise clé, ou tag GCM invalide
429	Quota Exceeded	Quota mensuel d’opérations atteint sur /v1/encrypt. Ce n’est pas une limite de débit : voir la section suivante.
500	Internal Server Error	Erreur interne. Un cas mérite d’être connu : unwrap refuse de rendre la clé si son entrée d’audit n’a pas pu être écrite.

Quotas et débit

Il n’existe aucune limite de débit. Aucun en-tête X-RateLimit n’est renvoyé, et aucune requête n’est refusée pour cause de fréquence.

Opération	Comptée	Peut être refusée ?
POST /v1/keys/:id/wrap	Oui, key.wrap	Non, jamais
POST /v1/keys/:id/unwrap	Oui, key.unwrap	Non, jamais
POST /v1/encrypt	Oui, encrypt	Oui, 429 au dépassement du quota mensuel
POST /v1/decrypt	Oui, decrypt	Non, délibérément : un quota ne doit pas vous enfermer hors de vos propres données

Les opérations d’enveloppe sont comptées pour votre facturation et votre journal d’audit, jamais pour vous refuser un appel : les paliers actifs portent un nombre d’opérations illimité.

Pagination

La pagination se fait par limit et offset. Il n’existe pas de curseur. limit vaut 50 par défaut et est plafonné à 100 côté serveur : demander davantage ne renvoie pas davantage.

GET /v1/audit?limit=50&offset=100

// Réponse
{
  "logs": [...],
  "count": 50,
  "total": 1247,
  "limit": 50,
  "offset": 100
}

Chiffrer / Déchiffrer