Architecture Multi-Tenant

Si vous exploitez une plateforme SaaS et souhaitez proposer la signature électronique comme fonctionnalité à vos propres clients, le modèle entreprise/espace de travail de Firma s’applique directement à une configuration multi-tenant : un espace de travail par client final, entièrement isolé et personnalisable indépendamment. Ce guide couvre le schéma de bout en bout — pour les détails, suivez les liens vers les guides dédiés.

Ceci est un guide d’architecture, pas une référence complète de l’API. Il se concentre sur la manière dont les éléments s’articulent pour les plateformes multi-tenant. Pour les corps de requête/réponse exhaustifs, suivez les liens vers Création d’espaces de travail, Marque blanche et Domaines personnalisés.

Vue d’ensemble de l’architecture : entreprise → espaces de travail

La hiérarchie de comptes de Firma comporte deux niveaux :

Entreprise — l’entité de facturation. Une entreprise détient un abonnement Firma, une clé API principale et des valeurs par défaut à l’échelle du compte.
Espaces de travail — unités organisationnelles au sein d’une entreprise. Chaque espace de travail possède ses propres modèles, demandes de signature, utilisation d’enveloppes, clé API et marque.

Pour une plateforme multi-tenant, votre entreprise Firma est votre plateforme, et chacun de vos clients finaux obtient son propre espace de travail. Les modèles, les demandes de signature et les données des signataires d’un espace de travail ne sont jamais visibles depuis un autre — il n’existe aucune exposition de documents ou de données entre espaces de travail.

Votre entreprise Firma (votre plateforme, un seul abonnement)
├── Espace de travail : Client A   → modèles, demandes de signature, marque, clé API
├── Espace de travail : Client B   → modèles, demandes de signature, marque, clé API
└── Espace de travail : Client C   → modèles, demandes de signature, marque, clé API

La marque, les conditions, les modèles d’email et plusieurs paramètres d’affichage suivent une cascade entreprise → espace de travail : définissez une base au niveau de l’entreprise, puis remplacez-la par espace de travail uniquement lorsqu’un client a besoin de quelque chose de différent. Un paramètre d’espace de travail laissé à null hérite de la valeur de l’entreprise. Cela signifie que l’intégration d’un nouveau client ne nécessite de définir que ce qui est réellement différent pour lui — tout le reste retombe sur la valeur par défaut de votre plateforme. Consultez Hiérarchie des paramètres pour l’ensemble des règles de cascade.

Un espace de travail par client final est le choix par défaut approprié. Ne répartissez un même client sur plusieurs espaces de travail que s’il possède des équipes ou unités commerciales véritablement distinctes ayant besoin de leurs propres bibliothèques de modèles isolées et de leur propre suivi d’utilisation — consultez Espaces de travail.

Provisionner un espace de travail par client

Lorsqu’un nouveau client s’inscrit sur votre plateforme, créez son espace de travail Firma dans le cadre de votre propre flux d’intégration.

Créez l'espace de travail

Appelez POST /workspaces avec la clé API maîtresse de votre plateforme lorsqu’un nouveau client s’inscrit :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp" }'

La réponse inclut l’id du nouvel espace de travail, son api_key de production et son test_api_key. Conservez l’id de l’espace de travail avec l’enregistrement du client dans votre propre base de données — vous l’utiliserez pour chaque appel API ultérieur associé à ce client.

Appliquez la marque

Importez le logo du client et définissez ses couleurs immédiatement après la création (voir Marque par client ci-dessous), afin que l’espace de travail ne connaisse jamais un moment sans marque.

Stockez la clé propre à l'espace de travail

Décidez si votre backend appellera Firma avec la clé maîtresse de votre plateforme (avec workspace_id dans le corps de la requête) ou avec la clé propre à l’espace de travail. Consultez Isolation des clés API pour connaître le compromis.

Les formats complets de requête/réponse, le listage et la mise à jour des espaces de travail sont couverts dans Création d’espaces de travail.

Marque par client

Chaque espace de travail peut remplacer le logo et les couleurs par défaut de votre plateforme, afin que les signataires de chaque client voient la marque de ce client, ni la vôtre ni celle de Firma. Logo. Importez un logo spécifique à l’espace de travail, qui remplace votre logo au niveau de l’entreprise uniquement pour cet espace de travail :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/tenant-logo.png"

PNG ou JPEG, jusqu’à 2 Mo. La suppression du logo de l’espace de travail retombe sur votre logo au niveau de l’entreprise, et non sur l’absence de logo — définissez donc une valeur par défaut sensée pour votre plateforme dès l’intégration. Couleurs. Définissez la palette de couleurs de l’espace de travail (color_primary, color_background, color_card, entre autres) via PUT /workspace/{workspace_id}/settings. C’est la même ressource de paramètres qui est utilisée pour les autres options d’affichage par client, comme show_signature_frame et show_qr_code.

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'

Masquez votre propre marque, à l’échelle de la plateforme. show_custom_branding_only est un interrupteur au niveau de l’entreprise, pas par espace de travail — il supprime la marque Firma pour toute votre entreprise (tous vos clients à la fois). Si vous appliquez une marque blanche pour vos propres clients, activez-le une seule fois au niveau de l’entreprise plutôt que d’essayer de le définir par espace de travail. La référence complète des couleurs, les conditions personnalisées pour les signataires et la personnalisation du libellé du bouton de signature sont documentées dans Marque blanche.

Domaines d’email par client

Si un client souhaite que les invitations de signature proviennent de son propre domaine (noreply@sign.tenant.com) plutôt que du domaine de votre plateforme, configurez un domaine d’email au niveau de l’espace de travail. Les domaines d’espace de travail remplacent le domaine au niveau de l’entreprise uniquement pour cet espace de travail — tout le reste utilise par défaut le domaine de votre plateforme. Le flux de vérification est le même processus en quatre étapes (ajouter le domaine → vérifier la propriété via un enregistrement TXT → finaliser → vérifier le DNS) que pour les domaines au niveau de l’entreprise, simplement sur des endpoints propres à l’espace de travail :

Action	Endpoint
Ajouter le domaine	`POST /workspace/{workspace_id}/domains`
Vérifier la propriété	`POST /workspace/{workspace_id}/domains/{id}/verify-ownership`
Finaliser (obtenir les enregistrements DNS)	`POST /workspace/{workspace_id}/domains/{id}/finalize`
Vérifier le DNS	`POST /workspace/{workspace_id}/domains/{id}/verify-dns`

La plupart des plateformes multi-tenant n’en ont besoin que pour les clients qui le demandent explicitement. Le laisser non défini signifie que l’espace de travail du client hérite simplement du domaine de votre plateforme au niveau de l’entreprise (ou du domaine par défaut de Firma) — aucune action requise dans le cas courant.

Pour les enregistrements DNS exacts, les états de vérification et la résolution des conflits DKIM avec d’autres fournisseurs, consultez Domaines personnalisés. Pour les corps complets de requête/réponse de chaque endpoint de domaine, consultez Domaines de messagerie personnalisés.

Isolation et gestion des clés API

Chaque espace de travail obtient sa propre clé API de production et de test dès sa création, indépendante des clés de tout autre espace de travail et de la clé maîtresse de votre entreprise. Deux schémas d’intégration :

Clé maîtresse, workspace_id dans le corps — votre backend détient une seule clé API (celle de l’entreprise) et transmet workspace_id à chaque requête (création de modèles, envoi de demandes de signature, etc.). Plus simple à exploiter ; une seule clé à faire tourner. C’est le choix par défaut approprié pour la plupart des plateformes, puisque votre backend constitue déjà la frontière de confiance entre vos clients et Firma.
Clés propres à chaque client — remettez directement la clé d’espace de travail de chaque client à ce client (par exemple si le client exploite son propre backend et appelle Firma sans passer par vos serveurs). N’utilisez cette approche que lorsqu’un client a réellement besoin d’un accès API direct ; cela signifie que vous distribuez et faites désormais tourner N clés au lieu d’une seule.

N’exposez jamais l’un ou l’autre type de clé à un navigateur. Si un flux doit être déclenché depuis le frontend de votre client, faites-le appeler votre backend, qui détient la clé et appelle Firma côté serveur.

Faire tourner une clé d’espace de travail compromise ou divulguée sans régénérer la clé de toute votre entreprise :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/regenerate \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key_type": "live" }'

Cela émet une nouvelle clé et accorde à l’ancienne un délai de grâce de 24 heures (expires_at) plutôt que de la désactiver instantanément, afin que les intégrations en cours ne se cassent pas en pleine requête. Une fois que vous avez confirmé que la nouvelle clé fonctionne, expirez l’ancienne immédiatement plutôt que d’attendre la fin du délai de grâce :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/api-key/expire \
  -H "Authorization: Bearer $FIRMA_API_KEY"

Les deux endpoints sont limités à 1 requête/minute et sont rejetés sur les espaces de travail protégés (espaces de travail détenus par le système qui ne peuvent pas être supprimés ni modifiés via les flux normaux) — une réponse 403 avec PROTECTED_WORKSPACE indique que vous en avez ciblé un par erreur. La régénération des clés live et test sont des opérations indépendantes ; régénérer l’une n’affecte jamais l’autre.

Éditeurs intégrés par client

Pour permettre aux propres utilisateurs d’un client de créer des modèles ou de configurer des demandes de signature sans quitter votre produit, intégrez les éditeurs de Firma avec un JWT de courte durée plutôt que d’exposer une clé API au navigateur :

// Your backend, scoped to the tenant's workspace/template
const token = await generateTemplateToken(templateId)

<iframe
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>

Comme le JWT est généré pour un modèle spécifique (et que ce modèle appartient à un espace de travail spécifique), la frontière entre clients est imposée par le token lui-même — un token émis pour le modèle du Client A ne peut pas être rejoué contre les données du Client B. Les éditeurs intégrés n’affichent déjà que le logo et les couleurs propres à l’espace de travail, sans marque Firma, si bien qu’un token correctement délimité vous procure à la fois l’isolation entre clients et la marque blanche en une seule étape. Consultez Éditeur de modèles intégrable et Éditeur de demandes de signature intégrable pour le flux complet de génération de JWT, le cycle de vie du token et l’intégration frontend (HTML et React). Pour intégrer le flux de signature lui-même, côté signataire, consultez Signature intégrable.

Assembler le tout

Un flux d’intégration multi-tenant typique, de bout en bout :

Le client s’inscrit sur votre plateforme → POST /workspaces crée son espace de travail Firma.
Importez son logo et définissez ses couleurs (ou laissez les deux non définis pour hériter de la valeur par défaut de votre plateforme).
S’il le demande, configurez un domaine d’email au niveau de l’espace de travail et/ou des conditions personnalisées pour les signataires.
Votre backend stocke l’id de l’espace de travail avec l’enregistrement du client et l’utilise (avec votre clé API maîtresse) pour chaque modèle, demande de signature et webhook associé à ce client.
Si les propres utilisateurs du client doivent créer des modèles ou configurer des demandes de signature dans l’application, générez des JWT par modèle et intégrez les éditeurs.

Guides associés

Création d’espaces de travail — CRUD des espaces de travail, listage et l’indicateur protected
Marque blanche — référence complète de marque, conditions, modèles d’email et intégration
Domaines personnalisés — enregistrements DNS, états de vérification et résolution des conflits DKIM
Éditeur de modèles intégrable · Éditeur de demandes de signature intégrable · Signature intégrable
Webhooks — suivez l’activité de signature par espace de travail client

Guides de Démarrage

Guides avancés

Architecture Multi-Tenant

Vue d’ensemble de l’architecture : entreprise → espaces de travail

Provisionner un espace de travail par client

Marque par client

Domaines d’email par client

Isolation et gestion des clés API

Éditeurs intégrés par client

Assembler le tout

Guides associés

​Vue d’ensemble de l’architecture : entreprise → espaces de travail

​Provisionner un espace de travail par client

​Marque par client

​Domaines d’email par client

​Isolation et gestion des clés API

​Éditeurs intégrés par client

​Assembler le tout

​Guides associés

Vue d’ensemble de l’architecture : entreprise → espaces de travail

Provisionner un espace de travail par client

Marque par client

Domaines d’email par client

Isolation et gestion des clés API

Éditeurs intégrés par client

Assembler le tout

Guides associés