API

API y servidor MCP de Sig.Surf

Sig.Surf tiene una REST API pública y un servidor MCP remoto. Un asistente puede crearle a alguien una firma de correo sin cuenta y darle un enlace para guardarla; con una clave de API, un servidor puede gestionar los empleados de la organización, y un asistente desde el que una persona ha iniciado sesión en Sig.Surf puede trabajar con las firmas guardadas de esa persona.

Empieza aquí

  • Descripción OpenAPI 3.1: /api/v1/openapi.json. Se genera a partir de los mismos esquemas con los que valida la API, así que coincide con el comportamiento real.
  • URL base de REST: https://sig.surf/api/v1. JSON de entrada y de salida.
  • Servidor MCP: https://sig.surf/mcp (Streamable HTTP). Funciona sin cuenta, con inicio de sesión con OAuth o con una clave de API.

Crea una firma sin cuenta

  1. GET /api/v1/templates lista todas las plantillas de la galería con su id, su categoría, los campos que usa, su SignatureDocument y una vista previa generada con valores de ejemplo. No hacen falta credenciales.
  2. POST /api/v1/signatures con { "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, o con un document completo en lugar de templateId. La respuesta contiene html apto para correo, text sin formato, warnings de validación, un claimUrl y un claimToken.
  3. Dale a la persona el claimUrl. Al abrirlo e iniciar sesión con Google, la firma se guarda en su cuenta de Sig.Surf.
  4. Hasta que se reclame, léela o modifícala con GET o PATCH /api/v1/signatures/{id} y la cabecera X-Claim-Token. Las firmas sin reclamar caducan a los 30 días.

Solo se almacena un hash del token de reclamación. Una vez reclamada la firma, o después de que caduque, el token deja de funcionar.

Endpoints

Método y rutaQué haceCredenciales
GET /api/v1/templatesListar plantillasNinguna
POST /api/v1/signaturesCrea una firmaNinguna, clave de API o sesión
GET /api/v1/signatures/{id}Obtener una firmaToken de reclamación, clave de API o sesión
PATCH /api/v1/signatures/{id}Actualizar una firmaToken de reclamación, clave de API o sesión
GET /api/v1/signaturesListar las firmas de tu organizaciónClave de API o sesión
DELETE /api/v1/signatures/{id}Eliminar una firmaClave de API o sesión
POST /api/v1/signatures/claimReclamar una firma anónimaSesión
GET, POST /api/v1/employeesListar o añadir empleadosClave de API o sesión
GET, PATCH /api/v1/employees/{id}Obtener o actualizar un empleadoClave de API o sesión
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}Listar, crear o revocar claves de APISesión (propietario o administrador)
GET /api/v1/extension/signaturesLas firmas del usuario con sesión iniciada, para la extensión de ChromeSesión
GET /api/v1/openapi.jsonEl documento OpenAPINinguna

Autenticación

  • Clave de API: Authorization: Bearer ssk_…. Una clave pertenece a una sola organización y actúa como administrador de ella, así que guárdala en un servidor. Los propietarios y los administradores crean y revocan claves con los endpoints /api/v1/api-keys con la sesión iniciada; Sig.Surf solo almacena un hash y muestra la clave una única vez.
  • Sesión: la cookie de inicio de sesión de sig.surf, para las páginas propias de Sig.Surf y la extensión de Chrome. Quienes están en varios espacios de trabajo eligen uno con la cabecera Sig.Surf-Workspace. Las escrituras autenticadas con la cookie se rechazan desde otros orígenes.
  • Nada: plantillas, creación de firmas, y lectura o edición de una firma sin reclamar con su token de reclamación.
  • Token de acceso de OAuth: solo para el servidor MCP, descrito más abajo. La REST API no acepta estos tokens.

Convenciones

  • Los errores son { "error": { "code": "snake_case", "message": "…" } } con el estado HTTP correspondiente, por ejemplo 422 unknown_template, 404 invalid_claim_token, 410 claim_expired.
  • Las listas son { "data": [...], "nextCursor": string | null }; pasa cursor y limit (de 1 a 100, 25 por defecto) para paginar.
  • Los ID son UUID y las marcas de tiempo son ISO 8601 en UTC.
  • El cuerpo de las solicitudes tiene un máximo de 64 KiB (413 payload_too_large).
  • Quienes llaman sin credenciales tienen un límite de 120 solicitudes por minuto y 30 firmas nuevas por hora por dirección de cliente; al superarlo, la respuesta es 429 rate_limited con una cabecera Retry-After.
  • Los navegadores pueden llamar desde cualquier origen a los endpoints que no necesitan credenciales (plantillas, crear una firma, leer o editar una con su token de reclamación, el documento OpenAPI). Las llamadas entre orígenes nunca llevan cookies, y una clave de API no se puede enviar desde un navegador en otro sitio.

Servidor MCP

Apunta un cliente MCP a https://sig.surf/mcp (Streamable HTTP). Las herramientas validan con los mismos esquemas que la REST API. list_templates devuelve una lista compacta (id, nombre, descripción, categoría, campos), opcionalmente de una sola category; pasa hasta 10 ids para obtener sus documentos y vistas previas.

HerramientaSin cuentaCon sesión iniciada (permiso de OAuth)Clave de API
list_templatesSíSíSí
create_signatureSí (devuelve un enlace de reclamación)signatures:write (se guarda en la cuenta)Sí
get_signatureCon el token de reclamaciónsignatures:readSí
update_signatureCon el token de reclamaciónsignatures:writeSí
list_signaturesNosignatures:readSí
list_employeesNoemployees:read, solo propietario o administradorSí
create_employee, update_employeeNoemployees:write, solo propietario o administradorSí

Todavía no hay herramientas para campañas.

Iniciar sesión con OAuth

El servidor MCP es un recurso protegido de OAuth 2.1 y Sig.Surf es su servidor de autorización, conforme a la especificación de autorización de MCP del 2026-07-28. Un cliente compatible con la autorización de MCP no necesita configuración: llama a una herramienta que requiere cuenta, recibe un 401 con una cabecera WWW-Authenticate y sigue a partir de ahí. La persona inicia sesión en Sig.Surf con Google y ve una página que nombra la aplicación y lo que pide.

  • Metadatos del recurso protegido (RFC 9728): https://sig.surf/.well-known/oauth-protected-resource/mcp.
  • Metadatos del servidor de autorización (RFC 8414): https://sig.surf/.well-known/oauth-authorization-server/api/auth. El emisor es https://sig.surf/api/auth.
  • Registro de clientes: se admiten, y se prefieren, los Client ID Metadata Documents (el client_id es la dirección HTTPS del documento de metadatos del cliente). Dynamic Client Registration (RFC 7591) también está abierto, para los clientes que no tienen otra cosa. Todos los clientes son clientes públicos: no se emite ningún secreto de cliente, aunque se pida.
  • Solo flujo de código de autorización con PKCE (S256). Envía resource=https://sig.surf/mcp; los tokens quedan vinculados a esa dirección y se rechazan en cualquier otro lugar, incluida la REST API.
  • Permisos: signatures:read, signatures:write, employees:read, employees:write, y offline_access para obtener un token de actualización. Una respuesta 401 o 403 insufficient_scope indica el permiso que necesita la herramienta, de modo que un cliente puede empezar con poco y pedir más.
  • Los tokens de acceso duran una hora. Los tokens de actualización duran 30 días desde su último uso y se sustituyen en cada uso; volver a usar uno antiguo pone fin a la concesión. Los tokens se pueden revocar en el endpoint de revocación (RFC 7009), y un token revocado deja de funcionar en la siguiente solicitud.

Un token nunca tiene más autoridad que la que tiene en ese momento la persona que lo concedió. Las herramientas de firmas solo llegan a las firmas de esa persona. Los permisos de empleados solo puede concederlos un propietario o un administrador del espacio de trabajo, y Sig.Surf vuelve a comprobar la pertenencia y el rol de la persona en cada llamada, de modo que el acceso termina cuando deja el espacio de trabajo o deja de ser administrador. Una concesión pertenece a un solo espacio de trabajo: el primero de la persona.

El inicio de sesión con OAuth se ha probado de principio a fin con el cliente oficial del SDK de TypeScript de MCP. Todavía no se ha probado con todos los asistentes; si el tuyo no puede conectarse, las herramientas que no necesitan cuenta siguen funcionando.

También legible por máquinas

  • Todas las páginas de marketing y de documentación se sirven también en Markdown: añade .md a la URL, o usa /index.md para la página de inicio.
  • llms.txt lista las páginas con descripciones de una línea, y llms-full.txt contiene su texto completo.
  • pricing.json y pricing.md recogen todos los planes, precios y límites.
  • sitemap.xml lista todas las páginas.

Esta página también está disponible en Markdown.