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

  1. GET /api/v1/templates elenca tutti i modelli della galleria con id, categoria, campi usati, SignatureDocument e un'anteprima generata con valori di esempio. Non servono credenziali.
  2. POST /api/v1/signatures con { "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, oppure con un document completo al posto di templateId. La risposta contiene html adatto alle email, text semplice, i warnings del lint, un claimUrl e un claimToken.
  3. Dai alla persona il claimUrl. Aprendolo e accedendo con Google, la firma viene salvata nel suo account Sig.Surf.
  4. Finché non viene riscattata, puoi leggerla o modificarla con GET o PATCH /api/v1/signatures/{id} e l'header X-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 percorsoChe cosa faCredenziali
GET /api/v1/templatesElencare i modelliNessuna
POST /api/v1/signaturesCrea una firmaNessuna, chiave API o sessione
GET /api/v1/signatures/{id}Ottenere una firmaToken di riscatto, chiave API o sessione
PATCH /api/v1/signatures/{id}Aggiornare una firmaToken di riscatto, chiave API o sessione
GET /api/v1/signaturesElencare le firme della tua organizzazioneChiave API o sessione
DELETE /api/v1/signatures/{id}Eliminare una firmaChiave API o sessione
POST /api/v1/signatures/claimRiscattare una firma anonimaSessione
GET, POST /api/v1/employeesElencare o aggiungere dipendentiChiave API o sessione
GET, PATCH /api/v1/employees/{id}Ottenere o aggiornare un dipendenteChiave API o sessione
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}Elencare, creare o revocare chiavi APISessione (proprietario o amministratore)
GET /api/v1/extension/signaturesLe firme dell'utente che ha effettuato l'accesso, per l'estensione di ChromeSessione
GET /api/v1/openapi.jsonIl documento OpenAPINessuna

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-keys dopo 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 esempio 422 unknown_template, 404 invalid_claim_token, 410 claim_expired.
  • Gli elenchi sono { "data": [...], "nextCursor": string | null }; passa cursor e limit (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_limited con un header Retry-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.

StrumentoSenza accountCon accesso effettuato (ambito OAuth)Chiave API
list_templatesSìSìSì
create_signatureSì (restituisce un link di riscatto)signatures:write (salvata nell'account)Sì
get_signatureCon il token di riscattosignatures:readSì
update_signatureCon il token di riscattosignatures:writeSì
list_signaturesNosignatures:readSì
list_employeesNoemployees:read, solo proprietario o amministratoreSì
create_employee, update_employeeNoemployees:write, solo proprietario o amministratoreSì

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). Invia resource=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, e offline_access per un refresh token. Una risposta 401 o 403 insufficient_scope indica 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 .md all'URL, oppure usa /index.md per 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.