# API e server MCP di Sig.Surf

Fonte: https://sig.surf/it/docs/api (versione Markdown della pagina)

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](https://sig.surf/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 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-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.

| 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`). 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](https://sig.surf/llms.txt) elenca le pagine con una descrizione di una riga, e [llms-full.txt](https://sig.surf/llms-full.txt) ne contiene il testo completo.
- [pricing.json](https://sig.surf/pricing.json) e [pricing.md](https://sig.surf/pricing.md) riportano ogni piano, prezzo e limite.
- [sitemap.xml](https://sig.surf/sitemap.xml) elenca tutte le pagine.
