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
GET /api/v1/templateslistet 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.POST /api/v1/signaturesmit{ "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }oder mit einem vollständigendocumentstatttemplateId. Die Antwort enthält E-Mail-tauglicheshtml, reinentext, Lint-warnings, eineclaimUrlund einclaimToken.- Gib der Person die
claimUrl. Wenn sie sie öffnet und sich mit Google anmeldet, wird die Signatur in ihrem Sig.Surf-Konto gespeichert. - Bis sie übernommen wurde, liest oder änderst du sie mit
GEToderPATCH /api/v1/signatures/{id}und dem HeaderX-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 Pfad | Was es macht | Zugangsdaten |
|---|---|---|
GET /api/v1/templates | Vorlagen auflisten | Keine |
POST /api/v1/signatures | Signatur anlegen | Keine, API-Schlüssel oder Sitzung |
GET /api/v1/signatures/{id} | Eine Signatur abrufen | Claim-Token, API-Schlüssel oder Sitzung |
PATCH /api/v1/signatures/{id} | Eine Signatur aktualisieren | Claim-Token, API-Schlüssel oder Sitzung |
GET /api/v1/signatures | Die Signaturen deiner Organisation auflisten | API-Schlüssel oder Sitzung |
DELETE /api/v1/signatures/{id} | Eine Signatur löschen | API-Schlüssel oder Sitzung |
POST /api/v1/signatures/claim | Eine anonyme Signatur übernehmen | Sitzung |
GET, POST /api/v1/employees | Mitarbeitende auflisten oder hinzufügen | API-Schlüssel oder Sitzung |
GET, PATCH /api/v1/employees/{id} | Mitarbeitende abrufen oder aktualisieren | API-Schlüssel oder Sitzung |
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id} | API-Schlüssel auflisten, erstellen oder widerrufen | Sitzung (Inhaber oder Admin) |
GET /api/v1/extension/signatures | Die Signaturen des angemeldeten Nutzers für die Chrome-Erweiterung | Sitzung |
GET /api/v1/openapi.json | Das OpenAPI-Dokument | Keine |
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 Beispiel422 unknown_template,404 invalid_claim_token,410 claim_expired. - Listen haben die Form
{ "data": [...], "nextCursor": string | null }. Zum Blättern übergibst ducursorundlimit(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_limitedmit einemRetry-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.
| Tool | Ohne Konto | Angemeldet (OAuth-Scope) | API-Schlüssel |
|---|---|---|---|
list_templates | Ja | Ja | Ja |
create_signature | Ja (liefert einen Claim-Link) | signatures:write (im Konto gespeichert) | Ja |
get_signature | Mit dem Claim-Token | signatures:read | Ja |
update_signature | Mit dem Claim-Token | signatures:write | Ja |
list_signatures | Nein | signatures:read | Ja |
list_employees | Nein | employees:read, nur Inhaber oder Admin | Ja |
create_employee, update_employee | Nein | employees:write, nur Inhaber oder Admin | Ja |
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 isthttps://sig.surf/api/auth. - Client-Registrierung: Client ID Metadata Documents (die
client_idist 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). Senderesource=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:writeundoffline_accessfür ein Refresh-Token. Eine Antwort mit401oder403 insufficient_scopenennt 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
.mdan die URL an oder nimm/index.mdfü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.