API
API e server MCP di Sig.Surf
Sig.Surf ha una REST API pubblica e un server MCP remoto. Un assistente può creare una firma email per qualcuno senza account e dargli un link per salvarla; con una chiave API un server può gestire i dipendenti dell'organizzazione, e un assistente da cui una persona ha effettuato l'accesso a Sig.Surf può lavorare con le firme salvate di quella persona.
Comincia da qui
- Descrizione OpenAPI 3.1: /api/v1/openapi.json. È generata dagli stessi schemi con cui l'API convalida le richieste, quindi corrisponde al comportamento reale.
- URL di base REST:
https://sig.surf/api/v1. JSON in entrata e in uscita. - Server MCP:
https://sig.surf/mcp(Streamable HTTP). Funziona senza account, con accesso OAuth o con una chiave API.
Creare una firma senza account
GET /api/v1/templateselenca tutti i modelli della galleria con id, categoria, campi usati, SignatureDocument e un'anteprima generata con valori di esempio. Non servono credenziali.POST /api/v1/signaturescon{ "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, oppure con undocumentcompleto al posto ditemplateId. La risposta contienehtmladatto alle email,textsemplice, iwarningsdel lint, unclaimUrle unclaimToken.- Dai alla persona il
claimUrl. Aprendolo e accedendo con Google, la firma viene salvata nel suo account Sig.Surf. - Finché non viene riscattata, puoi leggerla o modificarla con
GEToPATCH /api/v1/signatures/{id}e l'headerX-Claim-Token. Le firme non riscattate scadono dopo 30 giorni.
Del token di riscatto viene conservato solo un hash. Quando una firma viene riscattata, o dopo la scadenza, il token smette di funzionare.
Endpoint
| Metodo e percorso | Che cosa fa | Credenziali |
|---|---|---|
GET /api/v1/templates | Elencare i modelli | Nessuna |
POST /api/v1/signatures | Crea una firma | Nessuna, chiave API o sessione |
GET /api/v1/signatures/{id} | Ottenere una firma | Token di riscatto, chiave API o sessione |
PATCH /api/v1/signatures/{id} | Aggiornare una firma | Token di riscatto, chiave API o sessione |
GET /api/v1/signatures | Elencare le firme della tua organizzazione | Chiave API o sessione |
DELETE /api/v1/signatures/{id} | Eliminare una firma | Chiave API o sessione |
POST /api/v1/signatures/claim | Riscattare una firma anonima | Sessione |
GET, POST /api/v1/employees | Elencare o aggiungere dipendenti | Chiave API o sessione |
GET, PATCH /api/v1/employees/{id} | Ottenere o aggiornare un dipendente | Chiave API o sessione |
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id} | Elencare, creare o revocare chiavi API | Sessione (proprietario o amministratore) |
GET /api/v1/extension/signatures | Le firme dell'utente che ha effettuato l'accesso, per l'estensione di Chrome | Sessione |
GET /api/v1/openapi.json | Il documento OpenAPI | Nessuna |
Autenticazione
- Chiave API:
Authorization: Bearer ssk_…. Una chiave appartiene a una sola organizzazione e agisce come suo amministratore, quindi tienila su un server. Proprietari e amministratori creano e revocano le chiavi con gli endpoint/api/v1/api-keysdopo aver effettuato l'accesso; Sig.Surf conserva solo un hash e mostra la chiave una volta sola. - Sessione: il cookie di accesso di sig.surf, per le pagine di Sig.Surf e per l'estensione di Chrome. Chi fa parte di più workspace ne sceglie uno con l'header
Sig.Surf-Workspace. Le scritture autenticate dal cookie vengono rifiutate se arrivano da altre origini. - Niente: modelli, creazione di firme, e lettura o modifica di una firma non riscattata con il suo token di riscatto.
- Token di accesso OAuth: solo per il server MCP, descritto più sotto. La REST API non accetta questi token.
Convenzioni
- Gli errori sono
{ "error": { "code": "snake_case", "message": "…" } }con lo stato HTTP corrispondente, per esempio422 unknown_template,404 invalid_claim_token,410 claim_expired. - Gli elenchi sono
{ "data": [...], "nextCursor": string | null }; passacursorelimit(da 1 a 100, predefinito 25) per scorrere le pagine. - Gli ID sono UUID e i timestamp sono ISO 8601 in UTC.
- Il corpo delle richieste è limitato a 64 KiB (
413 payload_too_large). - Chi chiama senza credenziali è limitato a 120 richieste al minuto e 30 nuove firme all'ora per indirizzo client; oltre il limite la risposta è
429 rate_limitedcon un headerRetry-After. - I browser possono chiamare da qualsiasi origine gli endpoint che non richiedono credenziali (modelli, creazione di una firma, lettura o modifica di una firma con il suo token di riscatto, documento OpenAPI). Le chiamate cross-origin non portano mai cookie, e una chiave API non può essere inviata da un browser su un altro sito.
Server MCP
Punta un client MCP su https://sig.surf/mcp (Streamable HTTP). Gli strumenti convalidano con gli stessi schemi della REST API. list_templates restituisce un elenco compatto (id, nome, descrizione, categoria, campi), se vuoi per una sola category; passa fino a 10 ids per ottenere i loro documenti e le anteprime.
| Strumento | Senza account | Con accesso effettuato (ambito OAuth) | Chiave API |
|---|---|---|---|
list_templates | Sì | Sì | Sì |
create_signature | Sì (restituisce un link di riscatto) | signatures:write (salvata nell'account) | Sì |
get_signature | Con il token di riscatto | signatures:read | Sì |
update_signature | Con il token di riscatto | signatures:write | Sì |
list_signatures | No | signatures:read | Sì |
list_employees | No | employees:read, solo proprietario o amministratore | Sì |
create_employee, update_employee | No | employees:write, solo proprietario o amministratore | Sì |
Non ci sono ancora strumenti per le campagne.
Accedere con OAuth
Il server MCP è una risorsa protetta OAuth 2.1 e Sig.Surf è il suo server di autorizzazione, secondo la specifica di autorizzazione MCP del 2026-07-28. Un client che supporta l'autorizzazione MCP non ha bisogno di configurazione: chiama uno strumento che richiede un account, riceve 401 con un header WWW-Authenticate e prosegue da lì. La persona accede a Sig.Surf con Google e vede una pagina che indica l'applicazione e che cosa chiede.
- Metadati della risorsa protetta (RFC 9728):
https://sig.surf/.well-known/oauth-protected-resource/mcp. - Metadati del server di autorizzazione (RFC 8414):
https://sig.surf/.well-known/oauth-authorization-server/api/auth. L'issuer èhttps://sig.surf/api/auth. - Registrazione dei client: i Client ID Metadata Documents (il
client_idè l'indirizzo HTTPS del documento di metadati del client) sono supportati e preferiti. Anche la Dynamic Client Registration (RFC 7591) è aperta, per i client che non hanno altro. Ogni client è un client pubblico: non viene emesso alcun client secret, nemmeno se viene richiesto. - Solo flusso authorization code con PKCE (
S256). Inviaresource=https://sig.surf/mcp; i token sono legati a quell'indirizzo e vengono rifiutati ovunque altrove, REST API compresa. - Ambiti:
signatures:read,signatures:write,employees:read,employees:write, eoffline_accessper un refresh token. Una risposta401o403 insufficient_scopeindica l'ambito che serve allo strumento, così un client può partire con poco e chiedere di più. - I token di accesso durano un'ora. I refresh token durano 30 giorni dall'ultimo utilizzo e vengono sostituiti a ogni utilizzo; riusarne uno vecchio fa terminare l'autorizzazione. I token si possono revocare all'endpoint di revoca (RFC 7009), e un token revocato smette di funzionare dalla richiesta successiva.
Un token non ha mai più autorità di quanta ne abbia in quel momento la persona che l'ha concesso. Gli strumenti per le firme raggiungono solo le firme di quella persona. Gli ambiti sui dipendenti possono essere concessi solo da un proprietario o da un amministratore del workspace, e Sig.Surf ricontrolla l'appartenenza e il ruolo della persona a ogni chiamata, quindi l'accesso finisce quando lascia il workspace o smette di essere amministratore. Un'autorizzazione appartiene a un solo workspace: il primo della persona.
L'accesso con OAuth è stato testato da capo a fondo con il client ufficiale dell'SDK TypeScript di MCP. Non è ancora stato provato con tutti gli assistenti; se il tuo non riesce a collegarsi, gli strumenti che non richiedono un account funzionano comunque.
Leggibile anche dalle macchine
- Ogni pagina del sito e della documentazione è servita anche in Markdown: aggiungi
.mdall'URL, oppure usa/index.mdper la home page. - llms.txt elenca le pagine con una descrizione di una riga, e llms-full.txt ne contiene il testo completo.
- pricing.json e pricing.md riportano ogni piano, prezzo e limite.
- sitemap.xml elenca tutte le pagine.
Questa pagina è disponibile anche in Markdown.