API

API et serveur MCP de Sig.Surf

Sig.Surf propose une API REST publique et un serveur MCP distant. Un assistant peut créer une signature d'e-mail pour quelqu'un sans compte et lui remettre un lien pour l'enregistrer. Avec une clé API, un serveur peut gérer les employés de l'organisation, et un assistant depuis lequel une personne s'est connectée à Sig.Surf peut travailler sur les signatures enregistrées de cette personne.

Par où commencer

  • Description OpenAPI 3.1 : /api/v1/openapi.json. Elle est générée à partir des schémas que l'API utilise pour valider, et correspond donc au comportement réel.
  • URL de base REST : https://sig.surf/api/v1. JSON en entrée et en sortie.
  • Serveur MCP : https://sig.surf/mcp (Streamable HTTP). Fonctionne sans compte, avec une connexion OAuth ou avec une clé API.

Créer une signature sans compte

  1. GET /api/v1/templates liste tous les modèles de la galerie avec leur id, leur catégorie, les champs qu'ils utilisent, leur SignatureDocument et un aperçu généré avec des valeurs d'exemple. Aucun identifiant requis.
  2. POST /api/v1/signatures avec { "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, ou avec un document complet à la place de templateId. La réponse contient un html adapté aux e-mails, un text brut, des warnings de vérification, un claimUrl et un claimToken.
  3. Donnez le claimUrl à la personne. En l'ouvrant et en se connectant avec Google, elle enregistre la signature dans son compte Sig.Surf.
  4. Tant qu'elle n'est pas récupérée, lisez-la ou modifiez-la avec GET ou PATCH /api/v1/signatures/{id} et l'en-tête X-Claim-Token. Les signatures non récupérées expirent au bout de 30 jours.

Seule une empreinte (hash) du jeton de récupération est stockée. Une fois la signature récupérée, ou après son expiration, le jeton ne fonctionne plus.

Points de terminaison

Méthode et cheminCe qu'il faitIdentifiants
GET /api/v1/templatesLister les modèlesAucun
POST /api/v1/signaturesCréez une signatureAucun, clé API ou session
GET /api/v1/signatures/{id}Obtenir une signatureJeton de récupération, clé API ou session
PATCH /api/v1/signatures/{id}Mettre à jour une signatureJeton de récupération, clé API ou session
GET /api/v1/signaturesLister les signatures de votre organisationClé API ou session
DELETE /api/v1/signatures/{id}Supprimer une signatureClé API ou session
POST /api/v1/signatures/claimRécupérer une signature anonymeSession
GET, POST /api/v1/employeesLister ou ajouter des employésClé API ou session
GET, PATCH /api/v1/employees/{id}Obtenir ou mettre à jour un employéClé API ou session
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}Lister, créer ou révoquer des clés APISession (propriétaire ou administrateur)
GET /api/v1/extension/signaturesLes signatures de l'utilisateur connecté, pour l'extension ChromeSession
GET /api/v1/openapi.jsonLe document OpenAPIAucun

Authentification

  • Clé API : Authorization: Bearer ssk_…. Une clé appartient à une seule organisation et agit comme un administrateur de celle-ci. Gardez-la donc sur un serveur. Les propriétaires et les administrateurs créent et révoquent les clés avec les points de terminaison /api/v1/api-keys une fois connectés. Sig.Surf ne stocke qu'une empreinte (hash) et n'affiche la clé qu'une fois.
  • Session : le cookie de connexion de sig.surf, pour les pages de Sig.Surf et l'extension Chrome. Les personnes membres de plusieurs espaces de travail en choisissent un avec l'en-tête Sig.Surf-Workspace. Les écritures authentifiées par le cookie sont refusées depuis d'autres origines.
  • Rien : les modèles, la création de signatures, et la lecture ou la modification d'une signature non récupérée avec son jeton de récupération.
  • Jeton d'accès OAuth : pour le serveur MCP uniquement, décrit plus bas. L'API REST n'accepte pas ces jetons.

Conventions

  • Les erreurs ont la forme { "error": { "code": "snake_case", "message": "…" } } avec le code HTTP correspondant, par exemple 422 unknown_template, 404 invalid_claim_token, 410 claim_expired.
  • Les listes ont la forme { "data": [...], "nextCursor": string | null }. Passez cursor et limit (de 1 à 100, 25 par défaut) pour paginer.
  • Les identifiants sont des UUID et les horodatages sont au format ISO 8601, en UTC.
  • Le corps des requêtes est limité à 64 Kio (413 payload_too_large).
  • Les appelants sans identifiants sont limités à 120 requêtes par minute et 30 nouvelles signatures par heure et par adresse cliente. Au-delà, la réponse est 429 rate_limited avec un en-tête Retry-After.
  • Les navigateurs peuvent appeler depuis n'importe quelle origine les points de terminaison qui ne demandent pas d'identifiants (les modèles, la création d'une signature, sa lecture ou sa modification avec son jeton de récupération, le document OpenAPI). Les appels entre origines ne transportent jamais de cookies, et une clé API ne peut pas être envoyée depuis un navigateur sur un autre site.

Serveur MCP

Faites pointer un client MCP vers https://sig.surf/mcp (Streamable HTTP). Les outils valident avec les mêmes schémas que l'API REST. list_templates renvoie une liste compacte (id, nom, description, catégorie, champs), éventuellement pour une seule category. Passez jusqu'à 10 ids pour obtenir leurs documents et leurs aperçus.

OutilSans compteConnecté (champ d'application OAuth)Clé API
list_templatesOuiOuiOui
create_signatureOui (renvoie un lien de récupération)signatures:write (enregistrée dans le compte)Oui
get_signatureAvec le jeton de récupérationsignatures:readOui
update_signatureAvec le jeton de récupérationsignatures:writeOui
list_signaturesNonsignatures:readOui
list_employeesNonemployees:read, propriétaire ou administrateur uniquementOui
create_employee, update_employeeNonemployees:write, propriétaire ou administrateur uniquementOui

Il n'y a pas encore d'outils pour les campagnes.

Se connecter avec OAuth

Le serveur MCP est une ressource protégée OAuth 2.1 et Sig.Surf est son serveur d'autorisation, conformément à la spécification d'autorisation MCP du 2026-07-28. Un client qui prend en charge l'autorisation MCP n'a besoin d'aucune configuration : il appelle un outil qui demande un compte, reçoit un 401 avec un en-tête WWW-Authenticate, et poursuit à partir de là. La personne se connecte à Sig.Surf avec Google et voit une page qui nomme l'application et ce qu'elle demande.

  • Métadonnées de la ressource protégée (RFC 9728) : https://sig.surf/.well-known/oauth-protected-resource/mcp.
  • Métadonnées du serveur d'autorisation (RFC 8414) : https://sig.surf/.well-known/oauth-authorization-server/api/auth. L'émetteur est https://sig.surf/api/auth.
  • Enregistrement des clients : les Client ID Metadata Documents (le client_id est l'adresse HTTPS du document de métadonnées du client) sont pris en charge et recommandés. Le Dynamic Client Registration (RFC 7591) est également ouvert, pour les clients qui n'ont rien d'autre. Tous les clients sont des clients publics : aucun secret client n'est émis, même si un secret est demandé.
  • Flux par code d'autorisation avec PKCE (S256) uniquement. Envoyez resource=https://sig.surf/mcp. Les jetons sont liés à cette adresse et sont refusés partout ailleurs, y compris par l'API REST.
  • Champs d'application : signatures:read, signatures:write, employees:read, employees:write, et offline_access pour un jeton d'actualisation. Une réponse 401 ou 403 insufficient_scope nomme le champ d'application dont l'outil a besoin, ce qui permet à un client de commencer avec peu et d'en demander davantage.
  • Les jetons d'accès durent une heure. Les jetons d'actualisation durent 30 jours à compter de leur dernière utilisation et sont remplacés à chaque utilisation. Réutiliser un ancien jeton met fin à l'autorisation. Les jetons peuvent être révoqués au point de terminaison de révocation (RFC 7009), et un jeton révoqué cesse de fonctionner dès la requête suivante.

Un jeton ne donne jamais plus de droits que n'en a, à cet instant, la personne qui l'a accordé. Les outils de signature n'accèdent qu'aux signatures de cette personne. Les champs d'application liés aux employés ne peuvent être accordés que par un propriétaire ou un administrateur de l'espace de travail, et Sig.Surf revérifie l'appartenance et le rôle de la personne à chaque appel. L'accès prend donc fin quand elle quitte l'espace de travail ou cesse d'être administrateur. Une autorisation appartient à un seul espace de travail : le premier de la personne.

La connexion OAuth a été testée de bout en bout avec le client officiel du SDK TypeScript MCP. Elle n'a pas encore été essayée avec tous les assistants. Si le vôtre n'arrive pas à se connecter, les outils qui ne demandent pas de compte fonctionnent quand même.

Également lisible par les machines

  • Chaque page du site et de la documentation est aussi servie en Markdown : ajoutez .md à l'URL, ou utilisez /index.md pour la page d'accueil.
  • llms.txt liste les pages avec une description d'une ligne, et llms-full.txt contient leur texte intégral.
  • pricing.json et pricing.md contiennent tous les forfaits, prix et limites.
  • sitemap.xml liste toutes les pages.

Cette page est aussi disponible en Markdown.