API

API und MCP-Server von Sig.Surf

Sig.Surf hat eine öffentliche REST API und einen Remote-MCP-Server. Ein Assistent kann jemandem ohne Konto eine E-Mail-Signatur erstellen und einen Link zum Speichern mitgeben. Mit einem API-Schlüssel kann ein Server die Mitarbeitenden der Organisation verwalten, und ein Assistent, über den sich eine Person bei Sig.Surf angemeldet hat, kann mit den gespeicherten Signaturen dieser Person arbeiten.

Hier geht es los

  • OpenAPI-3.1-Beschreibung: /api/v1/openapi.json. Sie wird aus denselben Schemas erzeugt, mit denen die API validiert, und passt deshalb zum Verhalten.
  • REST-Basis-URL: https://sig.surf/api/v1. JSON rein und raus.
  • MCP-Server: https://sig.surf/mcp (Streamable HTTP). Funktioniert ohne Konto, mit Anmeldung per OAuth oder mit einem API-Schlüssel.

Eine Signatur ohne Konto erstellen

  1. GET /api/v1/templates listet jede Vorlage der Galerie mit ihrer ID, der Kategorie, den verwendeten Feldern, ihrem SignatureDocument und einer Vorschau, die mit Beispielwerten gerendert wurde. Zugangsdaten sind nicht nötig.
  2. POST /api/v1/signatures mit { "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } } oder mit einem vollständigen document statt templateId. Die Antwort enthält E-Mail-taugliches html, reinen text, Lint-warnings, eine claimUrl und ein claimToken.
  3. Gib der Person die claimUrl. Wenn sie sie öffnet und sich mit Google anmeldet, wird die Signatur in ihrem Sig.Surf-Konto gespeichert.
  4. Bis sie übernommen wurde, liest oder änderst du sie mit GET oder PATCH /api/v1/signatures/{id} und dem Header X-Claim-Token. Nicht übernommene Signaturen laufen nach 30 Tagen ab.

Vom Claim-Token wird nur ein Hash gespeichert. Sobald eine Signatur übernommen wurde oder abgelaufen ist, funktioniert das Token nicht mehr.

Endpunkte

Methode und PfadWas es machtZugangsdaten
GET /api/v1/templatesVorlagen auflistenKeine
POST /api/v1/signaturesSignatur anlegenKeine, API-Schlüssel oder Sitzung
GET /api/v1/signatures/{id}Eine Signatur abrufenClaim-Token, API-Schlüssel oder Sitzung
PATCH /api/v1/signatures/{id}Eine Signatur aktualisierenClaim-Token, API-Schlüssel oder Sitzung
GET /api/v1/signaturesDie Signaturen deiner Organisation auflistenAPI-Schlüssel oder Sitzung
DELETE /api/v1/signatures/{id}Eine Signatur löschenAPI-Schlüssel oder Sitzung
POST /api/v1/signatures/claimEine anonyme Signatur übernehmenSitzung
GET, POST /api/v1/employeesMitarbeitende auflisten oder hinzufügenAPI-Schlüssel oder Sitzung
GET, PATCH /api/v1/employees/{id}Mitarbeitende abrufen oder aktualisierenAPI-Schlüssel oder Sitzung
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}API-Schlüssel auflisten, erstellen oder widerrufenSitzung (Inhaber oder Admin)
GET /api/v1/extension/signaturesDie Signaturen des angemeldeten Nutzers für die Chrome-ErweiterungSitzung
GET /api/v1/openapi.jsonDas OpenAPI-DokumentKeine

Authentifizierung

  • API-Schlüssel: Authorization: Bearer ssk_…. Ein Schlüssel gehört zu einer Organisation und handelt als deren Admin, bewahre ihn also auf einem Server auf. Inhaber und Admins erstellen und widerrufen Schlüssel angemeldet über die Endpunkte unter /api/v1/api-keys. Sig.Surf speichert nur einen Hash und zeigt den Schlüssel ein einziges Mal an.
  • Sitzung: das Anmelde-Cookie von sig.surf, für die eigenen Seiten von Sig.Surf und die Chrome-Erweiterung. Wer in mehreren Workspaces ist, wählt einen mit dem Header Sig.Surf-Workspace. Schreibzugriffe, die per Cookie authentifiziert sind, werden von anderen Origins abgelehnt.
  • Nichts: Vorlagen, das Erstellen von Signaturen sowie das Lesen oder Bearbeiten einer nicht übernommenen Signatur mit ihrem Claim-Token.
  • OAuth-Zugriffstoken: nur für den MCP-Server, weiter unten beschrieben. Die REST API akzeptiert diese Tokens nicht.

Konventionen

  • Fehler haben die Form { "error": { "code": "snake_case", "message": "…" } } mit dem passenden HTTP-Status, zum Beispiel 422 unknown_template, 404 invalid_claim_token, 410 claim_expired.
  • Listen haben die Form { "data": [...], "nextCursor": string | null }. Zum Blättern übergibst du cursor und limit (1 bis 100, Standard 25).
  • IDs sind UUIDs, und Zeitstempel sind ISO 8601 in UTC.
  • Request-Bodys sind auf 64 KiB begrenzt (413 payload_too_large).
  • Aufrufe ohne Zugangsdaten sind pro Client-Adresse auf 120 Anfragen pro Minute und 30 neue Signaturen pro Stunde begrenzt. Wer darüber liegt, bekommt 429 rate_limited mit einem Retry-After-Header.
  • Browser können die Endpunkte, die keine Zugangsdaten brauchen (Vorlagen, eine Signatur erstellen, eine mit ihrem Claim-Token lesen oder bearbeiten, das OpenAPI-Dokument), von jedem Origin aus aufrufen. Cross-Origin-Aufrufe enthalten nie Cookies, und ein API-Schlüssel kann nicht aus einem Browser auf einer anderen Website gesendet werden.

MCP-Server

Richte einen MCP-Client auf https://sig.surf/mcp (Streamable HTTP). Die Tools validieren mit denselben Schemas wie die REST API. list_templates liefert eine kompakte Liste (ID, Name, Beschreibung, Kategorie, Felder), auf Wunsch für eine einzelne category. Übergib bis zu 10 ids, um deren Dokumente und Vorschauen zu bekommen.

ToolOhne KontoAngemeldet (OAuth-Scope)API-Schlüssel
list_templatesJaJaJa
create_signatureJa (liefert einen Claim-Link)signatures:write (im Konto gespeichert)Ja
get_signatureMit dem Claim-Tokensignatures:readJa
update_signatureMit dem Claim-Tokensignatures:writeJa
list_signaturesNeinsignatures:readJa
list_employeesNeinemployees:read, nur Inhaber oder AdminJa
create_employee, update_employeeNeinemployees:write, nur Inhaber oder AdminJa

Tools für Kampagnen gibt es noch nicht.

Anmelden mit OAuth

Der MCP-Server ist eine per OAuth 2.1 geschützte Ressource, und Sig.Surf ist sein Autorisierungsserver, gemäß der MCP-Autorisierungsspezifikation vom 2026-07-28. Ein Client, der die MCP-Autorisierung unterstützt, braucht keine Einrichtung: Er ruft ein Tool auf, das ein Konto braucht, bekommt 401 mit einem WWW-Authenticate-Header und macht von dort aus weiter. Die Person meldet sich mit Google bei Sig.Surf an und sieht eine Seite, die die Anwendung nennt und was sie anfragt.

  • Metadaten der geschützten Ressource (RFC 9728): https://sig.surf/.well-known/oauth-protected-resource/mcp.
  • Metadaten des Autorisierungsservers (RFC 8414): https://sig.surf/.well-known/oauth-authorization-server/api/auth. Der Issuer ist https://sig.surf/api/auth.
  • Client-Registrierung: Client ID Metadata Documents (die client_id ist die HTTPS-Adresse des Metadaten-Dokuments des Clients) werden unterstützt und bevorzugt. Dynamic Client Registration (RFC 7591) steht ebenfalls offen, für Clients, die nichts anderes haben. Jeder Client ist ein Public Client: Es wird kein Client-Secret ausgegeben, auch wenn eines angefragt wird.
  • Nur Authorization Code Flow mit PKCE (S256). Sende resource=https://sig.surf/mcp. Tokens sind an diese Adresse gebunden und werden überall sonst abgelehnt, auch von der REST API.
  • Scopes: signatures:read, signatures:write, employees:read, employees:write und offline_access für ein Refresh-Token. Eine Antwort mit 401 oder 403 insufficient_scope nennt den Scope, den das Tool braucht. Ein Client kann also mit wenig anfangen und nach mehr fragen.
  • Zugriffstokens gelten eine Stunde. Refresh-Tokens gelten 30 Tage ab ihrer letzten Verwendung und werden bei jeder Verwendung ersetzt. Wird ein altes noch einmal verwendet, endet die Freigabe. Tokens lassen sich am Revocation-Endpunkt (RFC 7009) widerrufen, und ein widerrufenes Token funktioniert bei der nächsten Anfrage nicht mehr.

Ein Token hat nie mehr Befugnisse, als die Person, die es gewährt hat, in diesem Moment selbst hat. Signatur-Tools erreichen nur die eigenen Signaturen dieser Person. Scopes für Mitarbeitende können nur Inhaber oder Admins des Workspace gewähren, und Sig.Surf prüft Mitgliedschaft und Rolle der Person bei jedem Aufruf erneut. Der Zugriff endet also, wenn sie den Workspace verlässt oder kein Admin mehr ist. Eine Freigabe gehört zu einem Workspace: dem ersten der Person.

Die Anmeldung per OAuth wurde von Anfang bis Ende mit dem offiziellen Client des MCP TypeScript SDK getestet. Mit jedem Assistenten wurde sie noch nicht ausprobiert. Wenn deiner sich nicht verbinden kann, funktionieren die Tools, die kein Konto brauchen, trotzdem.

Auch maschinenlesbar

  • Jede Marketing- und Doku-Seite gibt es auch als Markdown: Häng .md an die URL an oder nimm /index.md für die Startseite.
  • Die llms.txt listet die Seiten mit einzeiligen Beschreibungen, und die llms-full.txt enthält ihren vollständigen Text.
  • pricing.json und pricing.md enthalten jeden Tarif, jeden Preis und jedes Limit.
  • Die sitemap.xml listet jede Seite.

Diese Seite gibt es auch als Markdown.