# Sig.Surf API and MCP server

Source: https://sig.surf/docs/api (Markdown version of the page)

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](https://sig.surf/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 path | What it does | Credentials |
| --- | --- | --- |
| `GET /api/v1/templates` | List templates | None |
| `POST /api/v1/signatures` | Create a signature | None, API key or session |
| `GET /api/v1/signatures/{id}` | Get a signature | Claim token, API key or session |
| `PATCH /api/v1/signatures/{id}` | Update a signature | Claim token, API key or session |
| `GET /api/v1/signatures` | List your organization's signatures | API key or session |
| `DELETE /api/v1/signatures/{id}` | Delete a signature | API key or session |
| `POST /api/v1/signatures/claim` | Claim an anonymous signature | Session |
| `GET`, `POST /api/v1/employees` | List or add employees | API key or session |
| `GET`, `PATCH /api/v1/employees/{id}` | Get or update an employee | API key or session |
| `GET`, `POST /api/v1/api-keys`, `DELETE /api/v1/api-keys/{id}` | List, create or revoke API keys | Session (owner or admin) |
| `GET /api/v1/extension/signatures` | The signed-in user's signatures for the Chrome extension | Session |
| `GET /api/v1/openapi.json` | The OpenAPI document | None |

## 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.

| Tool | Without an account | Signed in (OAuth scope) | API key |
| --- | --- | --- | --- |
| `list_templates` | Yes | Yes | Yes |
| `create_signature` | Yes (returns a claim link) | `signatures:write` (saved to the account) | Yes |
| `get_signature` | With the claim token | `signatures:read` | Yes |
| `update_signature` | With the claim token | `signatures:write` | Yes |
| `list_signatures` | No | `signatures:read` | Yes |
| `list_employees` | No | `employees:read`, owner or admin only | Yes |
| `create_employee`, `update_employee` | No | `employees:write`, owner or admin only | Yes |

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](https://sig.surf/llms.txt) lists the pages with one-line descriptions, and [llms-full.txt](https://sig.surf/llms-full.txt) holds their full text.
- [pricing.json](https://sig.surf/pricing.json) and [pricing.md](https://sig.surf/pricing.md) carry every plan, price and limit.
- [sitemap.xml](https://sig.surf/sitemap.xml) lists every page.
