API
API e servidor MCP do Sig.Surf
O Sig.Surf tem uma REST API pública e um servidor MCP remoto. Um assistente pode criar uma assinatura de e-mail para alguém sem conta e entregar um link para salvá-la; com uma chave de API, um servidor pode gerenciar os colaboradores da organização, e um assistente a partir do qual a pessoa fez login no Sig.Surf pode trabalhar com as assinaturas salvas dessa pessoa.
Comece por aqui
- Descrição OpenAPI 3.1: /api/v1/openapi.json. Ela é gerada a partir dos mesmos esquemas com que a API valida, então corresponde ao comportamento.
- URL base da REST API:
https://sig.surf/api/v1. JSON na entrada e na saída. - Servidor MCP:
https://sig.surf/mcp(Streamable HTTP). Funciona sem conta, com login por OAuth ou com uma chave de API.
Crie uma assinatura sem conta
GET /api/v1/templateslista todos os modelos da galeria com id, categoria, os campos que cada um usa, seu SignatureDocument e uma prévia gerada com valores de exemplo. Não precisa de credenciais.POST /api/v1/signaturescom{ "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, ou com umdocumentcompleto no lugar detemplateId. A resposta trazhtmlseguro para e-mail,textsimples,warningsde lint, umclaimUrle umclaimToken.- Entregue o
claimUrlà pessoa. Ao abri-lo e fazer login com o Google, a assinatura é salva na conta dela no Sig.Surf. - Enquanto não for resgatada, leia ou altere a assinatura com
GETouPATCH /api/v1/signatures/{id}e o cabeçalhoX-Claim-Token. Assinaturas não resgatadas expiram após 30 dias.
Apenas um hash do token de resgate é armazenado. Depois que a assinatura é resgatada, ou depois que expira, o token deixa de funcionar.
Endpoints
| Método e caminho | O que faz | Credenciais |
|---|---|---|
GET /api/v1/templates | Listar modelos | Nenhuma |
POST /api/v1/signatures | Crie uma assinatura | Nenhuma, chave de API ou sessão |
GET /api/v1/signatures/{id} | Obter uma assinatura | Token de resgate, chave de API ou sessão |
PATCH /api/v1/signatures/{id} | Atualizar uma assinatura | Token de resgate, chave de API ou sessão |
GET /api/v1/signatures | Listar as assinaturas da sua organização | Chave de API ou sessão |
DELETE /api/v1/signatures/{id} | Excluir uma assinatura | Chave de API ou sessão |
POST /api/v1/signatures/claim | Resgatar uma assinatura anônima | Sessão |
GET, POST /api/v1/employees | Listar ou adicionar colaboradores | Chave de API ou sessão |
GET, PATCH /api/v1/employees/{id} | Obter ou atualizar um colaborador | Chave de API ou sessão |
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id} | Listar, criar ou revogar chaves de API | Sessão (proprietário ou administrador) |
GET /api/v1/extension/signatures | As assinaturas do usuário conectado, para a extensão do Chrome | Sessão |
GET /api/v1/openapi.json | O documento OpenAPI | Nenhuma |
Autenticação
- Chave de API:
Authorization: Bearer ssk_…. Uma chave pertence a uma organização e age como administrador dela, então mantenha-a em um servidor. Proprietários e administradores criam e revogam chaves com os endpoints/api/v1/api-keysenquanto estão conectados; o Sig.Surf armazena apenas um hash e mostra a chave uma única vez. - Sessão: o cookie de login do sig.surf, para as páginas do próprio Sig.Surf e a extensão do Chrome. Quem participa de vários espaços de trabalho escolhe um com o cabeçalho
Sig.Surf-Workspace. Gravações autenticadas pelo cookie são recusadas quando vêm de outras origens. - Nada: modelos, criação de assinaturas, e leitura ou edição de uma assinatura não resgatada com seu token de resgate.
- Token de acesso OAuth: somente para o servidor MCP, descrito abaixo. A REST API não aceita esses tokens.
Convenções
- Os erros têm o formato
{ "error": { "code": "snake_case", "message": "…" } }com o status HTTP correspondente, por exemplo422 unknown_template,404 invalid_claim_token,410 claim_expired. - As listas têm o formato
{ "data": [...], "nextCursor": string | null }; enviecursorelimit(de 1 a 100, padrão 25) para paginar. - Os IDs são UUIDs e as datas e horas seguem o ISO 8601, em UTC.
- O corpo das requisições tem limite de 64 KiB (
413 payload_too_large). - Chamadas sem credenciais têm limite de 120 requisições por minuto e 30 assinaturas novas por hora por endereço de cliente; passar disso retorna
429 rate_limitedcom um cabeçalhoRetry-After. - Navegadores podem chamar, de qualquer origem, os endpoints que não precisam de credenciais (modelos, criação de assinatura, leitura ou edição com o token de resgate, o documento OpenAPI). Chamadas entre origens nunca levam cookies, e uma chave de API não pode ser enviada de um navegador em outro site.
Servidor MCP
Aponte um cliente MCP para https://sig.surf/mcp (Streamable HTTP). As ferramentas validam com os mesmos esquemas da REST API. list_templates retorna uma lista compacta (id, nome, descrição, categoria, campos), opcionalmente de uma só category; envie até 10 ids para receber seus documentos e prévias.
| Ferramenta | Sem conta | Com login (escopo OAuth) | Chave de API |
|---|---|---|---|
list_templates | Sim | Sim | Sim |
create_signature | Sim (retorna um link de resgate) | signatures:write (salva na conta) | Sim |
get_signature | Com o token de resgate | signatures:read | Sim |
update_signature | Com o token de resgate | signatures:write | Sim |
list_signatures | Não | signatures:read | Sim |
list_employees | Não | employees:read, somente proprietário ou administrador | Sim |
create_employee, update_employee | Não | employees:write, somente proprietário ou administrador | Sim |
Ainda não há ferramentas de campanha.
Login com OAuth
O servidor MCP é um recurso protegido OAuth 2.1 e o Sig.Surf é seu servidor de autorização, seguindo a especificação de autorização do MCP de 2026-07-28. Um cliente compatível com a autorização do MCP não precisa de configuração: ele chama uma ferramenta que exige conta, recebe 401 com um cabeçalho WWW-Authenticate e segue a partir daí. A pessoa faz login no Sig.Surf com o Google e vê uma página com o nome do aplicativo e o que ele está pedindo.
- Metadados do recurso protegido (RFC 9728):
https://sig.surf/.well-known/oauth-protected-resource/mcp. - Metadados do servidor de autorização (RFC 8414):
https://sig.surf/.well-known/oauth-authorization-server/api/auth. O emissor éhttps://sig.surf/api/auth. - Registro de clientes: os Client ID Metadata Documents (o
client_idé o endereço HTTPS do documento de metadados do cliente) são aceitos e preferidos. O Dynamic Client Registration (RFC 7591) também está aberto, para clientes que não têm outra opção. Todo cliente é um cliente público: nenhum segredo de cliente é emitido, mesmo que seja solicitado. - Somente o fluxo de código de autorização com PKCE (
S256). Envieresource=https://sig.surf/mcp; os tokens ficam vinculados a esse endereço e são recusados em qualquer outro lugar, inclusive na REST API. - Escopos:
signatures:read,signatures:write,employees:read,employees:write, eoffline_accesspara um token de atualização. Uma resposta401ou403 insufficient_scopeinforma o escopo de que a ferramenta precisa, então um cliente pode começar com pouco e pedir mais. - Os tokens de acesso duram uma hora. Os tokens de atualização duram 30 dias a partir do último uso e são substituídos a cada uso; reutilizar um antigo encerra a concessão. Os tokens podem ser revogados no endpoint de revogação (RFC 7009), e um token revogado deixa de funcionar na requisição seguinte.
Um token nunca carrega mais autoridade do que a pessoa que o concedeu tem naquele momento. As ferramentas de assinatura alcançam apenas as assinaturas dessa pessoa. Os escopos de colaboradores só podem ser concedidos por um proprietário ou administrador do espaço de trabalho, e o Sig.Surf confere de novo a participação e a função da pessoa a cada chamada, então o acesso termina quando ela sai do espaço de trabalho ou deixa de ser administradora. Uma concessão pertence a um único espaço de trabalho: o primeiro da pessoa.
O login por OAuth foi testado de ponta a ponta com o cliente oficial do SDK TypeScript do MCP. Ele ainda não foi testado com todos os assistentes; se o seu não conseguir se conectar, as ferramentas que não precisam de conta continuam funcionando.
Também legível por máquinas
- Todas as páginas de marketing e de documentação também são servidas em Markdown: acrescente
.mdà URL, ou use/index.mdpara a página inicial. - O llms.txt lista as páginas com descrições de uma linha, e o llms-full.txt traz o texto completo delas.
- O pricing.json e o pricing.md trazem todos os planos, preços e limites.
- O sitemap.xml lista todas as páginas.
Esta página também está disponível em Markdown.