Guides
Build your integration with a coding agent
Use the SignatureAPI agent skills in Claude Code, Codex, or Cursor to design, build, and test your e-signature integration in test mode, then go live yourself.
A coding agent can write most of a SignatureAPI integration for you. The agent skills keep it on the current API: they read field names and events from the OpenAPI spec instead of guessing, and they build and prove the flow against test mode.
This guide walks through one integration, from installing the skills to the switch to live mode, which stays your decision.
Install the skills and the MCP server
From your project’s directory, let the CLI set up your agent:
npx signatureapi agent setup --skills --mcp --agent claude-code --yesnpx signatureapi agent setup --skills --mcp --agent codex --global --yesnpx signatureapi agent setup --skills --mcp --agent cursor --yesnpx skills add signatureapi/skillsThe first three install the skills and register the MCP server. Claude Code and Codex get the SignatureAPI plugin, which carries both. The last command installs the skills only, in any agent the skills CLI supports. See Agent setup for every agent and for what each command writes.
Reload the agent, and sign in to the MCP server when it asks.
Put a test API key in your env file
npx signatureapi initApprove the sign-in in your browser. The CLI writes the account’s test key into .env as SIGNATUREAPI_KEY (.env.local in Next.js projects) without printing it, and keeps the file out of Git. Your code and the skills’ scripts read the key from there. Never paste a key into the chat.
Design the flow
Describe what your app needs in your own words:
Our app sends each new customer a service agreement to sign after checkout,
and marks the order as signed when they are done. Plan the SignatureAPI
integration before writing any code.The architecture skill asks about the experience (who starts the flow, who signs, what counts as done), reads your codebase, and writes a design document for you to approve. Nothing is built until you approve it.
Build it against test mode
The design is approved. Build it.The integrate skill builds from the design document. It works in test mode only: it refuses a live key, creates test envelopes, receives webhooks locally, and walks a real browser through the signing ceremony to prove the flow end to end. Test envelopes are free and send no email.
To watch the webhooks yourself while you test, run your app’s handler and:
npx signatureapi listen --forward-to http://127.0.0.1:3000/webhooksDiagnose what misbehaves
The envelope for order 1042 never completed. Find out why.The diagnose skill fetches everything about the envelope and returns a verdict. It only reads, so it is safe on a production envelope too.
Go live yourself
When the flow passes in test mode, review the code like any other change. Then create a live key for the environment that runs it:
npx signatureapi init --mode live --env-path .env.productionIn production, set SIGNATUREAPI_KEY from your secret store. The go-live checklist lists what to check first.
Ask the docs
Any time, ask a question that needs a documented answer:
How do I make a signer approve a document before the second signer gets it?
Answer from the SignatureAPI docs and link the page.The docs skill reads the pages that cover the question and links every claim to its source. Without the skills, point the agent at llms.txt or a page’s .md version.
Keep the agent safe
- The skills and the MCP server act in test mode unless you ask for live.
- Keys stay in env files. The CLI and the MCP tools never print a key or a webhook signing secret.
- Review the agent’s changes before you merge them, as you would a colleague’s.
See Agent safety for the full set of patterns.