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
GET /api/v1/templatesgeeft 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.POST /api/v1/signaturesmet{ "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, of met een volledigdocumentin plaats vantemplateId. Het antwoord bevat e-mailveiligehtml, plattetext, lint-warnings, eenclaimUrlen eenclaimToken.- Geef de persoon de
claimUrl. Wie hem opent en inlogt met Google, slaat de handtekening op in het eigen Sig.Surf-account. - Totdat hij is geclaimd, lees of wijzig je hem met
GETofPATCH /api/v1/signatures/{id}en de headerX-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 pad | Wat hij doet | Inloggegevens |
|---|---|---|
GET /api/v1/templates | Sjablonen opvragen | Geen |
POST /api/v1/signatures | Maak een handtekening | Geen, API-sleutel of sessie |
GET /api/v1/signatures/{id} | Een handtekening ophalen | Claimtoken, API-sleutel of sessie |
PATCH /api/v1/signatures/{id} | Een handtekening bijwerken | Claimtoken, API-sleutel of sessie |
GET /api/v1/signatures | De handtekeningen van je organisatie opvragen | API-sleutel of sessie |
DELETE /api/v1/signatures/{id} | Een handtekening verwijderen | API-sleutel of sessie |
POST /api/v1/signatures/claim | Een anonieme handtekening claimen | Sessie |
GET, POST /api/v1/employees | Medewerkers opvragen of toevoegen | API-sleutel of sessie |
GET, PATCH /api/v1/employees/{id} | Een medewerker ophalen of bijwerken | API-sleutel of sessie |
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id} | API-sleutels opvragen, aanmaken of intrekken | Sessie (eigenaar of beheerder) |
GET /api/v1/extension/signatures | De handtekeningen van de ingelogde gebruiker voor de Chrome-extensie | Sessie |
GET /api/v1/openapi.json | Het OpenAPI-document | Geen |
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, bijvoorbeeld422 unknown_template,404 invalid_claim_token,410 claim_expired. - Lijsten zijn
{ "data": [...], "nextCursor": string | null }; geefcursorenlimit(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_limitedmet eenRetry-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.
| Tool | Zonder account | Ingelogd (OAuth-scope) | API-sleutel |
|---|---|---|---|
list_templates | Ja | Ja | Ja |
create_signature | Ja (geeft een claimlink terug) | signatures:write (opgeslagen in het account) | Ja |
get_signature | Met het claimtoken | signatures:read | Ja |
update_signature | Met het claimtoken | signatures:write | Ja |
list_signatures | Nee | signatures:read | Ja |
list_employees | Nee | employees:read, alleen eigenaar of beheerder | Ja |
create_employee, update_employee | Nee | employees:write, alleen eigenaar of beheerder | Ja |
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 ishttps://sig.surf/api/auth. - Clientregistratie: Client ID Metadata Documents (de
client_idis 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). Stuurresource=https://sig.surf/mcpmee; 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, enoffline_accessvoor een refreshtoken. Een antwoord401of403 insufficient_scopenoemt 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
.mdachter de URL, of gebruik/index.mdvoor 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.