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

  1. GET /api/v1/templates lista 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.
  2. POST /api/v1/signatures com { "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, ou com um document completo no lugar de templateId. A resposta traz html seguro para e-mail, text simples, warnings de lint, um claimUrl e um claimToken.
  3. Entregue o claimUrl à pessoa. Ao abri-lo e fazer login com o Google, a assinatura é salva na conta dela no Sig.Surf.
  4. Enquanto não for resgatada, leia ou altere a assinatura com GET ou PATCH /api/v1/signatures/{id} e o cabeçalho X-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 caminhoO que fazCredenciais
GET /api/v1/templatesListar modelosNenhuma
POST /api/v1/signaturesCrie uma assinaturaNenhuma, chave de API ou sessão
GET /api/v1/signatures/{id}Obter uma assinaturaToken de resgate, chave de API ou sessão
PATCH /api/v1/signatures/{id}Atualizar uma assinaturaToken de resgate, chave de API ou sessão
GET /api/v1/signaturesListar as assinaturas da sua organizaçãoChave de API ou sessão
DELETE /api/v1/signatures/{id}Excluir uma assinaturaChave de API ou sessão
POST /api/v1/signatures/claimResgatar uma assinatura anônimaSessão
GET, POST /api/v1/employeesListar ou adicionar colaboradoresChave de API ou sessão
GET, PATCH /api/v1/employees/{id}Obter ou atualizar um colaboradorChave de API ou sessão
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}Listar, criar ou revogar chaves de APISessão (proprietário ou administrador)
GET /api/v1/extension/signaturesAs assinaturas do usuário conectado, para a extensão do ChromeSessão
GET /api/v1/openapi.jsonO documento OpenAPINenhuma

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-keys enquanto 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 exemplo 422 unknown_template, 404 invalid_claim_token, 410 claim_expired.
  • As listas têm o formato { "data": [...], "nextCursor": string | null }; envie cursor e limit (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_limited com um cabeçalho Retry-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.

FerramentaSem contaCom login (escopo OAuth)Chave de API
list_templatesSimSimSim
create_signatureSim (retorna um link de resgate)signatures:write (salva na conta)Sim
get_signatureCom o token de resgatesignatures:readSim
update_signatureCom o token de resgatesignatures:writeSim
list_signaturesNãosignatures:readSim
list_employeesNãoemployees:read, somente proprietário ou administradorSim
create_employee, update_employeeNãoemployees:write, somente proprietário ou administradorSim

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). Envie resource=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, e offline_access para um token de atualização. Uma resposta 401 ou 403 insufficient_scope informa 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.md para 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.