Guides
Agent safety
Patterns that keep AI agents safe with SignatureAPI: test mode by default, human approval before live sends, scoped access, and keys kept out of the chat.
A live envelope emails real people and can produce a legally binding signature. An agent that sends one by mistake can’t take the email back. These patterns keep an agent useful while every live send stays a decision a person makes.
Test mode by default
Every SignatureAPI surface an agent uses starts in test mode, where envelopes are free, watermarked, not legally binding, and send no email:
| Surface | Default | How it goes live |
|---|---|---|
| MCP server | Every tool call acts in test mode. | The call passes mode: live. |
| Agent skills | The integrate skill works in test mode only and refuses a live key. | It doesn’t. Your code goes live with your live key. |
| CLI | Resource commands act in test mode. | --mode live, or a live API key. |
In test mode, the email log still records what recipients would have received. An agent reads it with list_emails and get_email, and can give you a test signing link, so you can check a whole flow without anyone being contacted.
Human approval before live sends
Make a person approve every live send. Three layers help:
- Ask the agent to stop and summarize. Put the rule in the prompt, the system prompt, or a skill: “Draft in test mode. Before any live-mode action, summarize it and wait for my explicit OK.”
- Let the client confirm. The MCP tools that act outside SignatureAPI (
create_envelope,resend_request,replace_recipient,create_ceremony, and the webhook writes) carry MCP’sdestructiveHint, so well-behaved clients ask you before each call. Don’t turn those confirmations off for a SignatureAPI connection that can use live mode. - Let the CLI confirm. In live mode,
envelopes create,recipients resend,recipients replace, andrecipients ceremonyask before they act, andenvelopes cancelandenvelopes deletealways ask. In a non-interactive shell they fail withconfirmation-requiredunless the command passes--yes. Pass--yesonly in scripts you wrote and reviewed, never on an agent’s behalf.
Draft first, then send: a test envelope never turns into a live one, so the live send is always a new, deliberate request.
A prompt rule that combines these:
When you work with SignatureAPI:
- Use test mode unless I explicitly ask for live mode in this conversation.
- Before any live-mode action (creating, resending, replacing, or creating a
ceremony), show me exactly what you will do and wait for my OK.
- Never cancel or delete an envelope unless I ask for that envelope.
- Never ask me for an API key or webhook signing secret, and never print one.
- After acting, confirm the result from the envelope's events, not from memory.Scoped access
- One account per connection. An MCP connection acts for the one organization chosen at sign-in. To act for another, the user authorizes again and chooses it.
- Live mode follows the role. A session whose organization role lacks live-mode access can’t go live: the MCP server refuses the call with
live-mode-unavailableand the CLI fails the same way. An agent can check first:whoamireportsmodes.live. See Users for who gets live-mode access. - Disconnect at any time. Settings → Applications in the Dashboard lists every connected agent. Disconnecting blocks the next request at once, even with an unexpired token. See Managing connections.
- Separate test and live keys. Keep them in separate env files or variables. The CLI refuses to write a key into a variable that holds the other mode’s key.
- No hosted MCP for multi-tenant products. The hosted server connects a person’s agent to their own account. An agent that serves your customers runs on your backend with the REST API, and your code decides which tenant sees what.
Credentials stay out of the chat
A tool result lands in the agent’s context, the client’s transcript, and the model provider’s logs. So:
- No MCP tool returns an API key or a webhook signing secret.
create_webhooklinks the Dashboard page that shows the secret, and the agent asks you to copy it into your environment. - The CLI writes keys and secrets into your env file and never prints them. Resource commands take a key from an env variable (
--api-key-var), never as a value. - Never paste a key into a chat. If one leaks, roll it:
npx signatureapi api-keys roll <key-id> --mode <mode> --replace.
Verify, don’t trust
Ask the agent to prove what happened from SignatureAPI’s own records: list_events for progress, get_envelope for status, list_webhook_attempts for deliveries. An event is a fact; a sentence in the chat is a claim.
Undo is limited
- Disconnecting an agent doesn’t undo what it already did.
- A sent envelope can be canceled while it is in progress, but the emails already went out.
- A completed envelope can’t be canceled.
Agents that sign
An agent with computer use can complete a ceremony as a recipient. Use that only for documents that were already reviewed and approved, and only on behalf of someone who authorized it. See Agentic ceremonies. When the signature needs no ceremony at all, use an automatic signer.