# Esign Comply: setup runbook for AI agents and AI coding tools

> The exact sequence an AI agent follows to add an Esign Comply ceremony to an application, from an empty account to a live key.
> Follow the steps in order. If a step fails or something here conflicts with the codebase, stop and ask your person.
> Use only the API methods and packages named here and in the documentation.

Related: [guide for AI agents](https://esigncomply.com/agents.md) · [credential rules](https://esigncomply.com/auth.md) · [project rules block](https://esigncomply.com/rules.md) · [index of all pages](https://esigncomply.com/llms.txt) · [quickstart](https://esigncomply.com/docs/quickstart.md) · [OpenAPI](https://esigncomply.com/openapi.json)

## Who does what

A person creates the account and accepts the terms once, at https://esigncomply.com/signup?next=/dashboard/agent. No card. After that an AI agent does everything with an agent token: create keys, register documents, build the flow, verify the domain, go live. The steps, with the exact labels of every page and the calls of the account API, are at https://esigncomply.com/agents.md.

What stays with the person:

- Creating the account: the email, the acceptance of the terms, and the 6-digit code from their inbox.
- Accepting legal terms or signing anything for the organization.
- Sign-in security: second factors.
- Creating agent tokens. You can revoke your own.
- Team members and roles.
- Billing and plan changes.

DNS is the one practical limit: an agent without access to the DNS provider asks the person to add one TXT record.

Rules that hold for every step:

- Never print, log or commit the agent token or a key. Never put one in client code or a URL.
- Publish the text of the person's legal documents as they give it to you. Never write or change it.
- Never pre-check an assent control, auto-submit, or call `.click()` on the user's behalf.
- Develop with the test key. The live key goes into the production environment only.

## 0. The account, the agent token, the test key

1. The person has an account. If not, give them https://esigncomply.com/signup?next=/dashboard/agent: they enter their email, tick one box and type the 6-digit code from their inbox. The Free plan needs no card.
2. You have an agent token in `ESIGNCOMPLY_AGENT_TOKEN` (it starts with `esc_agent_`). Sign-up ends on the page "Agent access", where the person presses "Create agent token" and pastes you the block it shows. Driving their logged-in browser, press it yourself.
3. Read the account and take the API base URL from it:

```bash
curl -s https://esigncomply.com/v1/agent \
  -H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN"
```

   The answer holds `api_url`, the domain with its DNS record, usage, `next_step` and `steps`. Store `api_url` as `ESIGNCOMPLY_API_URL` on the server. The Node SDK and the CLI read that variable. On this deployment it is `https://esigncomply.com/v1`.

4. Create the test key and store it as `ESIGNCOMPLY_API_KEY` in `.env.local` (or the platform's secret store):

```bash
curl -s -X POST https://esigncomply.com/v1/agent/api-keys \
  -H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "mode": "test" }'
```

   The key is in the field `key`, once. It starts with `esc_test_us_` or `esc_test_eu_`. In a browser the same key comes from https://esigncomply.com/dashboard, button "Create test key".
5. `.env.local` is in `.gitignore`.

Without an agent token you can still build: the person creates the test key in the dashboard and puts it in the environment themselves.

Packages (the only ones that exist): `esigncomply` (Node server SDK and CLI), `@esigncomply/browser`, `@esigncomply/react`, `esigncomply-verify`.

```bash
npm install esigncomply @esigncomply/browser
```

## 1. Verify the key

```bash
curl -s "$ESIGNCOMPLY_API_URL/usage" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

- `200` with `"object": "usage"`: continue. Check that `test_events.used_this_month` is below `test_events.quota_per_month`.
- `401 missing_api_key` or `invalid_api_key`: the environment variable is empty or holds another value. Create a key again (step 0) or ask your person to check it.
- `421 region_mismatch`: use the `host` named in the error.
- If the key starts with `esc_live_`: switch to the test key. Development and previews use test keys.

Never echo the key. To say which key is in use, name its prefix only.

## 2. Documents and versions

List what exists first, so that you do not create duplicates:

```bash
curl -s "$ESIGNCOMPLY_API_URL/documents?limit=100" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY"
```

Create each missing document, then publish one version of it from the text your person gives you. Versions are immutable: publish when the text is final.

```bash
curl -s "$ESIGNCOMPLY_API_URL/documents" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Terms of Service", "type": "terms" }'

curl -s "$ESIGNCOMPLY_API_URL/documents/doc_8Hq2/versions" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: tos-2026-11-21" \
  -d '{ "version_label": "2026-11-21", "language": "en", "content": { "format": "markdown", "text": "# Terms of Service\n..." }, "material_change": true }'
```

Document types: `terms`, `privacy_notice`, `nda`, `contract`, `consent`, `policy_ack`, `custom`. Use the documents the project has. If it has none, register a short sample document, put "Sample" in its name, and say so in your report. Reference: https://esigncomply.com/docs/api/documents.md

## 3. Profile, or a generated prompt

If there is a prompt generated in the dashboard (it starts with a line such as `Prompt esc_prompt_...`), follow that prompt: it carries the profile IDs, the document IDs and the rules for the selected packs. It takes precedence over this runbook where they differ. You can generate one yourself: https://esigncomply.com/dashboard/prompts, link "Generate a prompt", or `POST /v1/prompts/generate`.

Otherwise create a profile. This needs a `full_access` key, which the test key from step 0 is. In a browser: https://esigncomply.com/dashboard/profiles, link "New profile".

```bash
curl -s "$ESIGNCOMPLY_API_URL/profiles" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Signup", "jurisdictions": ["US-FED"], "method": "checkbox", "assurance_level": "L1" }'
```

- Terms and privacy acceptance at signup: `method: "checkbox"`, `assurance_level: "L1"`.
- NDAs and contracts: `method: "typed"`, `assurance_level: "L2"` (a one-time code by email inside the ceremony).
- Ask your person which jurisdictions apply. The choice of packs is theirs. Read the catalogue from `GET /v1/jurisdictions`; never hard-code it.

Preview what a session would require, without creating anything:

```bash
curl -s "$ESIGNCOMPLY_API_URL/jurisdictions/resolve" \
  -H "Authorization: Bearer $ESIGNCOMPLY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "profile": "prof_signup_4f1a", "signer": { "class": "consumer", "country": "US", "region": "US-CA" }, "documents": [{ "document": "doc_8Hq2", "version": "current" }], "context": { "purpose": "account_signup" } }'
```

Reference: https://esigncomply.com/docs/api/profiles.md · https://esigncomply.com/docs/guides/jurisdictions.md

## 4. Build

Build these five parts. The complete Next.js version is at https://esigncomply.com/docs/guides/nextjs.md.

1. **Server module.** One file that creates the client from the environment and is imported only by server code.

   ```ts
   // lib/esigncomply.ts
   import "server-only";
   import { EsignComply } from "esigncomply";
   export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!);
   ```

   Server SDK calls return `{ data, error }` and do not throw. Check `error` every time.

2. **Session on the server.** `esc.sessions.create(body, { idempotencyKey })` with the profile, the signer (`external_id`, `email`, `class`, `country`, and `region` from the form or account data, never from IP), the documents (`version: "current"`), and `context.url`. Send only `client_token` and `documents` to the browser. Save the signer ID and the pinned `version_id` values in server-owned state.

3. **Ceremony in the browser.** `EsignComply.attach({ clientToken })`, then satisfy every entry of the session's `required_steps`. Do not hard-code steps. For a signup acceptance: `presentDocument` for each version, `observeAssent({ region, checkbox, submit })`, then `complete()` from the user's real click. Render every entry of `required_strings` verbatim in the slot it names. Reference: https://esigncomply.com/docs/sdk/browser.md

   The assent region holds, in this order: an unchecked checkbox whose label states agreement to the named documents, the notice text with a link to each document, and one primary button. Notice wording: "By checking the box and clicking {button label}, you agree to the [document titles]."

4. **Server confirmation.** Before granting access, `esc.records.get(recordId)` and require: no error; `status` is `recorded`, `timestamped` or `anchored`; `livemode` is as expected; `signer.external_id` and the document version IDs equal the server-owned state. Reference: https://esigncomply.com/docs/guides/server-confirmation.md

5. **Webhook.** A route that reads the raw body, verifies it with `esc.webhooks.verify(rawBody, headers, process.env.ESIGNCOMPLY_WEBHOOK_SECRET!)`, is idempotent on `webhook-id`, handles `record.completed`, ignores unknown types and returns `200`. Reference: https://esigncomply.com/docs/api/webhooks.md

Each document is served at a stable page on the application's own domain that renders the registered version fetched from Esign Comply, unmodified. Never copy document text into the repository.

## 5. Run the conformance check

```bash
npx esigncomply check --url http://localhost:3000/signup
```

- Fix every finding marked `block`. Each finding names its rule (`CR-01` … `CR-28`), the measurement and a fix: https://esigncomply.com/docs/conformance.md
- List every finding marked `warn` in your report.
- In test mode findings never stop a record from being sealed, so read them: a `block` finding stops a live record.

Also confirm by test that submitting with the box unchecked does nothing, and that the server-confirmation route refuses a made-up record ID.

## 6. Make it the project's rule, and convert what exists

1. Add the block at https://esigncomply.com/rules.md to the file the project's AI tools read for standing instructions: `AGENTS.md`, or `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md` if the project already has one.
2. Search the project for every place where a person signs or accepts something: terms checkboxes on sign-up forms, checkout terms, NDA and contract pages, "I agree" buttons, and columns such as `accepted_terms_at`.
3. Convert one flow at a time through steps 2 to 5, then add it to the list at the end of the rules block: its path, what is signed or accepted, and its profile ID.
4. Leave the acceptance data the project already holds in place. New acceptances get records.
5. When a session is refused, the flow stops and tells the person. Never fall back to an acceptance with no record.

## 7. Go live

The Free plan goes live with no plan to choose, no card and no checkout. The terms and the Data Processing Agreement were accepted at sign-up.

1. Register the domain and read the TXT record:

```bash
curl -s -X PUT https://esigncomply.com/v1/agent/domain \
  -H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "domain": "app.example.com" }'
```

2. Publish the record in `verification` (`type`, `name`, `value`) at the DNS provider. Without access to it, give your person those three values.
3. Check it. `verified` is `true` once both public resolvers return the value:

```bash
curl -s -X POST https://esigncomply.com/v1/agent/domain/verify \
  -H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN"
```

4. Save the organization's details and create the live key in one call. Ask your person for the values:

```bash
curl -s -X POST https://esigncomply.com/v1/agent/go-live \
  -H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "organization": { "legal_name": "Acme, Inc.", "country": "US", "line1": "1 Main Street", "city": "Wilmington", "billing_email": "billing@acme.example" } }'
```

   A `201` carries the live key once, in `api_key.key`. Store it as `ESIGNCOMPLY_API_KEY` in the production environment only.
5. In a browser the same steps are at https://esigncomply.com/dashboard/domains and https://esigncomply.com/dashboard/go-live. The labels are in https://esigncomply.com/agents.md.

Free covers 10 live signatures a month. If you use all 10 in a month, the account locks until you upgrade to a paid plan. It does not unlock at the start of the next month. Past the limit, new live signatures can be refused, so upgrade before you get there.

Watch `GET /v1/usage` (`events.used` against `events.quota`) or `GET /v1/agent`, and tell your person before the month's 10 are used, because using all 10 locks the account until they upgrade.

## 8. Report to your person

1. Files created or changed.
2. The IDs you created: documents, versions, profiles, the domain.
3. Anything in this runbook or the generated prompt that you did not implement, and why.
4. The conformance summary: findings fixed, warnings left.
5. Where the keys are stored (the variable names, never the values) and how many live signatures the month has left.
6. What is theirs to do, if anything: the TXT record when you have no DNS access, and the steps listed under "Who does what".

## Errors you are likely to meet

| Code | Meaning | What to do |
|---|---|---|
| `steps_incomplete` | `complete()` ran before every required step was recorded | Record the steps in `missing_steps` first |
| `step_out_of_order` | An event arrived before a step it depends on | Call `attach()` first and follow `required_steps` |
| `domain_mismatch` | The page is not on localhost or a listed preview host (test), or not on the registered domain (live) | Add the preview host under "Test origins" at https://esigncomply.com/dashboard/domains |
| `client_token_expired` | The session reached its lifetime | Create a new session with a new idempotency key and attach again |
| `insufficient_permission` | The key's permission does not allow the call, or the step is the person's | Use a key with the permission, or tell your person which step it was |
| `quota_exhausted` | A new live session was refused: the plan's limit is passed | Stop the flow, tell the person, never record the acceptance without a session |
| `rate_limit_exceeded` | The Free plan allows 2 requests per second per key | Wait for `Retry-After` |

Every code: https://esigncomply.com/docs/api/errors.md
