MAFATE
Référence API

Chiffrer / Déchiffrer

Référence du mode serveur, où la donnée en clair transite par MAFATE pour y être chiffrée, et de l’empreinte déterministe qui rend un champ cherchable.

Ces deux points de terminaison sont refusés par défaut

Tout locataire créé depuis le 11/08/2026 porte envelope_only = true : /v1/encrypt et /v1/decrypt répondent 403 E_ENVELOPE_ONLY, et le refus est journalisé. Ce n’est pas une dépréciation, le mode serveur reste légitime pour un service qui ne peut pas exécuter de cryptographie côté client, mais il s’ouvre sur demande auprès du support.

Les points de terminaison du mode par défaut

POST/v1/encrypt

Chiffre une donnée texte avec la clé spécifiée. Retourne un ciphertext à stocker dans votre base de données.

Corps de la requête

ChampTypeRequisDescription
plaintextstringOuiDonnée à chiffrer (max 64 KB)
key_idstringOuiUUID de la clé, rendu par POST /v1/keys. Jamais son nom.
curl -s -X POST https://api.mafate.io/v1/encrypt \
  -H "Authorization: Bearer $MAFATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plaintext": "Jean Dupont",
    "key_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

# Reponse 200
{
  "ciphertext": "AQIDAHj8mK2z4vNpqRs7LmXoWtU1a9BcDE...",
  "wrapped_key": "CiQAe3kL9vXmPqR...",
  "iv": "9xK2mQ7bTfR1cVwE",
  "key_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "key_version": 2
}

# Reponse 403 sur un locataire en mode enveloppe, c'est-a-dire par defaut
{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "E_ENVELOPE_ONLY: ce locataire est en mode enveloppe, ou la donnee en clair ne transite jamais par MAFATE..."
}
POST/v1/decrypt

Déchiffre un ciphertext. Nécessite le key_id et le key_version stockés avec le ciphertext.

Corps de la requête

ChampTypeRequisDescription
ciphertextstringOuiLe ciphertext retourné par /encrypt
key_idstringOuiIdentifiant de la clé (stocké avec le ciphertext)
key_versionintegerOuiVersion de la clé (stockée avec le ciphertext)
curl -s -X POST https://api.mafate.io/v1/decrypt \
  -H "Authorization: Bearer $MAFATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ciphertext": "AQIDAHj8mK2z4vNpqRs7LmXoWtU1a9BcDE...",
    "wrapped_key": "CiQAe3kL9vXmPqR...",
    "iv": "9xK2mQ7bTfR1cVwE",
    "key_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "key_version": 2
  }'

# Reponse 200. Elle ne porte QUE le clair.
{
  "plaintext": "Jean Dupont"
}

# 422 Decryption Failed si le chiffre a ete altere ou la cle ne correspond pas.
API Clés
POST/v1/hashOuvert dans les deux modes

Calcule une empreinte déterministe liée à la clé, pour rendre un champ chiffré cherchable sans le déchiffrer. C’est le seul point de terminaison qui reçoit du clair sur un compte en mode enveloppe, et il est resté ouvert délibérément : le bloquer casserait le motif de recherche enseigné par les guides.

Permission requise : encrypt. Une clé désactivée fait échouer l’appel en 409.

# ⚠️ CET APPEL TRANSMET LE CLAIR A MAFATE, DANS LES DEUX MODES.
#
# C'est le seul, et il est ouvert meme en mode enveloppe : le bloquer casserait
# le motif de recherche que la documentation enseigne. Mais votre analyse
# d'impact doit le mentionner, et vous ne devez y passer que le champ que vous
# avez besoin de chercher.

curl -s -X POST https://api.mafate.io/v1/hash \
  -H "Authorization: Bearer $MAFATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "[email protected]",
    "key_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

# Reponse 200
{
  "hash": "a3f2b1c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f80",
  "key_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

# Le hachage est DETERMINISTE et lie a la cle : la meme valeur rend toujours la
# meme empreinte, ce qui la rend indexable. C'est aussi ce qui la rend
# vulnerable a une attaque par dictionnaire si votre base fuit : n'y passez pas
# un champ a faible entropie comme une date de naissance ou un code postal.
#
# ⚠️ Une rotation de la cle NE CHANGE PAS les empreintes deja calculees, mais
# une cle desactivee fait echouer l'appel (409 Conflict) : prevoyez la
# reindexation avant de detruire une cle qui sert au hachage.