API

Sig.Surf API and MCP server

Sig.Surf has a public REST API and a remote MCP server. An assistant can make someone an email signature without an account and hand them a link to save it; with an API key a server can manage the organization's employees, and an assistant a person has signed in to Sig.Surf from can work with that person's saved signatures.

Start here

  • OpenAPI 3.1 description: /api/v1/openapi.json. It is generated from the same schemas the API validates with, so it matches the behaviour.
  • REST base URL: https://sig.surf/api/v1. JSON in and out.
  • MCP server: https://sig.surf/mcp (Streamable HTTP). Works without an account, with OAuth sign-in, or with an API key.

Make a signature without an account

  1. GET /api/v1/templates lists every template in the gallery with its id, category, the fields it uses, its SignatureDocument and a preview rendered with sample values. No credentials needed.
  2. POST /api/v1/signatures with { "templateId": "quiet-line", "fields": { "fullName": "…", "email": "…" } }, or with a full document instead of templateId. The answer holds email-safe html, plain text, lint warnings, a claimUrl and a claimToken.
  3. Give the person the claimUrl. Opening it and signing in with Google saves the signature to their Sig.Surf account.
  4. Until it is claimed, read or change it with GET or PATCH /api/v1/signatures/{id} and the header X-Claim-Token. Unclaimed signatures expire after 30 days.

Only a hash of the claim token is stored. Once a signature is claimed, or after it expires, the token stops working.

Endpoints

Method and pathWhat it doesCredentials
GET /api/v1/templatesList templatesNone
POST /api/v1/signaturesCreate a signatureNone, API key or session
GET /api/v1/signatures/{id}Get a signatureClaim token, API key or session
PATCH /api/v1/signatures/{id}Update a signatureClaim token, API key or session
GET /api/v1/signaturesList your organization's signaturesAPI key or session
DELETE /api/v1/signatures/{id}Delete a signatureAPI key or session
POST /api/v1/signatures/claimClaim an anonymous signatureSession
GET, POST /api/v1/employeesList or add employeesAPI key or session
GET, PATCH /api/v1/employees/{id}Get or update an employeeAPI key or session
GET, POST /api/v1/api-keys, DELETE /api/v1/api-keys/{id}List, create or revoke API keysSession (owner or admin)
GET /api/v1/extension/signaturesThe signed-in user's signatures for the Chrome extensionSession
GET /api/v1/openapi.jsonThe OpenAPI documentNone

Authentication

  • API key: Authorization: Bearer ssk_…. A key belongs to one organization and acts as an admin of it, so keep it on a server. Owners and admins create and revoke keys with the /api/v1/api-keys endpoints while signed in; Sig.Surf stores only a hash and shows the key once.
  • Session: the sig.surf sign-in cookie, for Sig.Surf's own pages and the Chrome extension. People in several workspaces choose one with the Sig.Surf-Workspace header. Writes authenticated by the cookie are refused from other origins.
  • Nothing: templates, signature creation, and reading or editing an unclaimed signature with its claim token.
  • OAuth access token: for the MCP server only, described below. The REST API does not accept these tokens.

Conventions

  • Errors are { "error": { "code": "snake_case", "message": "…" } } with the matching HTTP status, for example 422 unknown_template, 404 invalid_claim_token, 410 claim_expired.
  • Lists are { "data": [...], "nextCursor": string | null }; pass cursor and limit (1 to 100, default 25) to page.
  • IDs are UUIDs and timestamps are ISO 8601 in UTC.
  • Request bodies are capped at 64 KiB (413 payload_too_large).
  • Callers without credentials are limited to 120 requests a minute and 30 new signatures an hour per client address; going over answers 429 rate_limited with a Retry-After header.
  • Browsers can call the endpoints that need no credentials (templates, creating a signature, reading or editing one with its claim token, the OpenAPI document) from any origin. Cross-origin calls never carry cookies, and an API key cannot be sent from a browser on another site.

MCP server

Point an MCP client at https://sig.surf/mcp (Streamable HTTP). The tools validate with the same schemas as the REST API. list_templates returns a compact list (id, name, description, category, fields), optionally for one category; pass up to 10 ids to get their documents and previews.

ToolWithout an accountSigned in (OAuth scope)API key
list_templatesYesYesYes
create_signatureYes (returns a claim link)signatures:write (saved to the account)Yes
get_signatureWith the claim tokensignatures:readYes
update_signatureWith the claim tokensignatures:writeYes
list_signaturesNosignatures:readYes
list_employeesNoemployees:read, owner or admin onlyYes
create_employee, update_employeeNoemployees:write, owner or admin onlyYes

There are no campaign tools yet.

Signing in with OAuth

The MCP server is an OAuth 2.1 protected resource and Sig.Surf is its authorization server, following the MCP authorization specification of 2026-07-28. A client that supports MCP authorization needs no setup: it calls a tool that needs an account, gets 401 with a WWW-Authenticate header, and takes it from there. The person signs in to Sig.Surf with Google and sees a page naming the application and what it asks for.

  • Protected resource metadata (RFC 9728): https://sig.surf/.well-known/oauth-protected-resource/mcp.
  • Authorization server metadata (RFC 8414): https://sig.surf/.well-known/oauth-authorization-server/api/auth. The issuer is https://sig.surf/api/auth.
  • Client registration: Client ID Metadata Documents (the client_id is the HTTPS address of the client's metadata document) are supported and preferred. Dynamic Client Registration (RFC 7591) is also open, for clients that have nothing else. Every client is a public client: no client secret is issued, even if one is asked for.
  • Authorization code flow with PKCE (S256) only. Send resource=https://sig.surf/mcp; tokens are bound to that address and are refused anywhere else, including the REST API.
  • Scopes: signatures:read, signatures:write, employees:read, employees:write, and offline_access for a refresh token. A 401 or 403 insufficient_scope answer names the scope the tool needs, so a client can start with little and ask for more.
  • Access tokens last one hour. Refresh tokens last 30 days from their last use and are replaced on every use; using an old one again ends the grant. Tokens can be revoked at the revocation endpoint (RFC 7009), and a revoked token stops working on the next request.

A token never carries more authority than the person who granted it has at that moment. Signature tools reach that person's own signatures only. Employee scopes can only be granted by an owner or admin of the workspace, and Sig.Surf checks the person's membership and role again on every call, so access ends when they leave the workspace or stop being an admin. A grant belongs to one workspace: the person's first.

OAuth sign-in has been tested end to end with the official MCP TypeScript SDK client. It has not yet been tried with every assistant; if yours cannot connect, the tools that need no account still work.

Also machine readable

  • Every marketing and docs page is also served as Markdown: add .md to the URL, or use /index.md for the home page.
  • llms.txt lists the pages with one-line descriptions, and llms-full.txt holds their full text.
  • pricing.json and pricing.md carry every plan, price and limit.
  • sitemap.xml lists every page.

This page is also available as Markdown.