API

Sig.Surf API en MCP-server

Sig.Surf heeft een openbare REST API en een externe MCP-server. Een assistent kan zonder account een e-mailhandtekening voor iemand maken en diegene een link geven om hem op te slaan; met een API-sleutel kan een server de medewerkers van de organisatie beheren, en een assistent van waaruit iemand bij Sig.Surf is ingelogd, kan met de opgeslagen handtekeningen van die persoon werken.

Begin hier

  • OpenAPI 3.1-beschrijving: /api/v1/openapi.json. Die wordt gegenereerd uit dezelfde schema's waarmee de API valideert, en komt dus overeen met het gedrag.
  • Basis-URL van REST: https://sig.surf/api/v1. JSON in en uit.
  • MCP-server: https://sig.surf/mcp (Streamable HTTP). Werkt zonder account, met inloggen via OAuth, of met een API-sleutel.

Een handtekening maken zonder account

  1. GET /api/v1/templates geeft elk sjabloon in de galerij met zijn id, categorie, de velden die het gebruikt, zijn SignatureDocument en een voorbeeld dat met voorbeeldwaarden is gerenderd. Geen inloggegevens nodig.
  2. POST /api/v1/signatures met { "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, of met een volledig document in plaats van templateId. Het antwoord bevat e-mailveilige html, platte text, lint-warnings, een claimUrl en een claimToken.
  3. Geef de persoon de claimUrl. Wie hem opent en inlogt met Google, slaat de handtekening op in het eigen Sig.Surf-account.
  4. Totdat hij is geclaimd, lees of wijzig je hem met GET of PATCH /api/v1/signatures/{id} en de header X-Claim-Token. Niet-geclaimde handtekeningen verlopen na 30 dagen.

Van het claimtoken wordt alleen een hash opgeslagen. Zodra een handtekening is geclaimd, of nadat hij is verlopen, werkt het token niet meer.

Endpoints

Methode en padWat hij doetInloggegevens
GET /api/v1/templatesSjablonen opvragenGeen
POST /api/v1/signaturesMaak een handtekeningGeen, API-sleutel of sessie
GET /api/v1/signatures/{id}Een handtekening ophalenClaimtoken, API-sleutel of sessie
PATCH /api/v1/signatures/{id}Een handtekening bijwerkenClaimtoken, API-sleutel of sessie
GET /api/v1/signaturesDe handtekeningen van je organisatie opvragenAPI-sleutel of sessie
DELETE /api/v1/signatures/{id}Een handtekening verwijderenAPI-sleutel of sessie
POST /api/v1/signatures/claimEen anonieme handtekening claimenSessie
GET, POST /api/v1/employeesMedewerkers opvragen of toevoegenAPI-sleutel of sessie
GET, PATCH /api/v1/employees/{id}Een medewerker ophalen of bijwerkenAPI-sleutel of sessie
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}API-sleutels opvragen, aanmaken of intrekkenSessie (eigenaar of beheerder)
GET /api/v1/extension/signaturesDe handtekeningen van de ingelogde gebruiker voor de Chrome-extensieSessie
GET /api/v1/openapi.jsonHet OpenAPI-documentGeen

Authenticatie

  • API-sleutel: Authorization: Bearer ssk_…. Een sleutel hoort bij één organisatie en handelt als beheerder daarvan, dus bewaar hem op een server. Eigenaren en beheerders maken sleutels aan en trekken ze in met de /api/v1/api-keys-endpoints terwijl ze zijn ingelogd; Sig.Surf slaat alleen een hash op en toont de sleutel één keer.
  • Sessie: de inlogcookie van sig.surf, voor de eigen pagina's van Sig.Surf en de Chrome-extensie. Wie in meerdere werkruimtes zit, kiest er een met de header Sig.Surf-Workspace. Schrijfacties die met de cookie zijn geauthenticeerd, worden vanaf andere origins geweigerd.
  • Niets: sjablonen, het maken van handtekeningen, en het lezen of bewerken van een niet-geclaimde handtekening met het bijbehorende claimtoken.
  • OAuth-toegangstoken: alleen voor de MCP-server, hieronder beschreven. De REST API accepteert deze tokens niet.

Conventies

  • Fouten zijn { "error": { "code": "snake_case", "message": "…" } } met de bijbehorende HTTP-status, bijvoorbeeld 422 unknown_template, 404 invalid_claim_token, 410 claim_expired.
  • Lijsten zijn { "data": [...], "nextCursor": string | null }; geef cursor en limit (1 tot 100, standaard 25) mee om te bladeren.
  • ID's zijn UUID's en tijdstempels zijn ISO 8601 in UTC.
  • Request-body's zijn begrensd op 64 KiB (413 payload_too_large).
  • Aanroepers zonder inloggegevens zijn beperkt tot 120 verzoeken per minuut en 30 nieuwe handtekeningen per uur per clientadres; wie daaroverheen gaat, krijgt 429 rate_limited met een Retry-After-header.
  • Browsers kunnen de endpoints waarvoor geen inloggegevens nodig zijn (sjablonen, een handtekening maken, er een lezen of bewerken met het claimtoken, het OpenAPI-document) vanaf elke origin aanroepen. Cross-origin-aanroepen sturen nooit cookies mee, en een API-sleutel kan niet worden verstuurd vanuit een browser op een andere site.

MCP-server

Laat een MCP-client verwijzen naar https://sig.surf/mcp (Streamable HTTP). De tools valideren met dezelfde schema's als de REST API. list_templates geeft een compacte lijst terug (id, naam, beschrijving, categorie, velden), eventueel voor één category; geef maximaal 10 ids mee om hun documenten en voorbeelden te krijgen.

ToolZonder accountIngelogd (OAuth-scope)API-sleutel
list_templatesJaJaJa
create_signatureJa (geeft een claimlink terug)signatures:write (opgeslagen in het account)Ja
get_signatureMet het claimtokensignatures:readJa
update_signatureMet het claimtokensignatures:writeJa
list_signaturesNeesignatures:readJa
list_employeesNeeemployees:read, alleen eigenaar of beheerderJa
create_employee, update_employeeNeeemployees:write, alleen eigenaar of beheerderJa

Er zijn nog geen tools voor campagnes.

Inloggen met OAuth

De MCP-server is een met OAuth 2.1 beschermde resource en Sig.Surf is de bijbehorende autorisatieserver, volgens de MCP-autorisatiespecificatie van 2026-07-28. Een client die MCP-autorisatie ondersteunt, heeft geen configuratie nodig: hij roept een tool aan waarvoor een account nodig is, krijgt 401 met een WWW-Authenticate-header, en gaat van daaruit verder. De persoon logt met Google in bij Sig.Surf en ziet een pagina met de naam van de applicatie en wat die vraagt.

  • Metadata van de beschermde resource (RFC 9728): https://sig.surf/.well-known/oauth-protected-resource/mcp.
  • Metadata van de autorisatieserver (RFC 8414): https://sig.surf/.well-known/oauth-authorization-server/api/auth. De issuer is https://sig.surf/api/auth.
  • Clientregistratie: Client ID Metadata Documents (de client_id is het HTTPS-adres van het metadatadocument van de client) worden ondersteund en hebben de voorkeur. Dynamic Client Registration (RFC 7591) staat ook open, voor clients die niets anders hebben. Elke client is een publieke client: er wordt geen client secret uitgegeven, ook niet als erom wordt gevraagd.
  • Alleen de authorization code flow met PKCE (S256). Stuur resource=https://sig.surf/mcp mee; tokens zijn aan dat adres gebonden en worden overal elders geweigerd, ook door de REST API.
  • Scopes: signatures:read, signatures:write, employees:read, employees:write, en offline_access voor een refreshtoken. Een antwoord 401 of 403 insufficient_scope noemt de scope die de tool nodig heeft, zodat een client met weinig kan beginnen en om meer kan vragen.
  • Toegangstokens zijn één uur geldig. Refreshtokens zijn 30 dagen geldig vanaf het laatste gebruik en worden bij elk gebruik vervangen; wie een oude opnieuw gebruikt, beëindigt de toestemming. Tokens kunnen worden ingetrokken via het revocation-endpoint (RFC 7009), en een ingetrokken token werkt bij het volgende verzoek niet meer.

Een token heeft nooit meer bevoegdheid dan de persoon die het heeft verleend op dat moment zelf heeft. Handtekeningtools komen alleen bij de eigen handtekeningen van die persoon. Medewerker-scopes kunnen alleen worden verleend door een eigenaar of beheerder van de werkruimte, en Sig.Surf controleert bij elke aanroep opnieuw het lidmaatschap en de rol van de persoon, dus de toegang stopt wanneer die de werkruimte verlaat of geen beheerder meer is. Een toestemming hoort bij één werkruimte: de eerste van de persoon.

Inloggen met OAuth is van begin tot eind getest met de officiële MCP TypeScript SDK-client. Het is nog niet met elke assistent geprobeerd; als die van jou geen verbinding krijgt, werken de tools waarvoor geen account nodig is nog steeds.

Ook leesbaar voor machines

  • Elke marketing- en documentatiepagina wordt ook als Markdown aangeboden: zet .md achter de URL, of gebruik /index.md voor de homepage.
  • llms.txt somt de pagina's op met een beschrijving van één regel, en llms-full.txt bevat hun volledige tekst.
  • pricing.json en pricing.md bevatten elk abonnement, elke prijs en elke limiet.
  • sitemap.xml somt elke pagina op.

Deze pagina is ook beschikbaar als Markdown.