---
title: "Agent safety"
description: "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."
canonical: "https://signatureapi.com/docs/ai-toolkit/guides/agent-safety"
source: "https://signatureapi.com/docs/ai-toolkit/guides/agent-safety.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T13:19:17Z"
---

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

_Last verified against API version 1.18.0._

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](https://signatureapi.com/docs/api/test-mode), where envelopes are free, watermarked, not legally binding, and send no email:

| Surface                                                                       | Default                                                             | How it goes live                                    |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------- |
| [MCP server](https://signatureapi.com/docs/ai-toolkit/mcp/tools)              | Every tool call acts in test mode.                                  | The call passes `mode: live`.                       |
| [Agent skills](https://signatureapi.com/docs/ai-toolkit/develop/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](https://signatureapi.com/docs/cli/resources)                            | 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's `destructiveHint`, 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`, and `recipients ceremony` ask before they act, and `envelopes cancel` and `envelopes delete` always ask. In a non-interactive shell they fail with `confirmation-required` unless the command passes `--yes`. Pass `--yes` only 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:

```text
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-unavailable` and the CLI fails the same way. An agent can check first: `whoami` reports `modes.live`. See [Users](https://signatureapi.com/docs/dashboard/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](https://signatureapi.com/docs/ai-toolkit/mcp/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](https://signatureapi.com/docs/api/overview), 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_webhook` links 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](https://signatureapi.com/docs/api/resources/envelopes/cancel) 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](https://signatureapi.com/docs/ai-toolkit/agentic-ceremonies). When the signature needs no ceremony at all, use an [automatic signer](https://signatureapi.com/docs/api/resources/recipients/automatic-signer).
