# Esign Comply: credential handling rules

> How people and AI agents handle Esign Comply credentials: the agent token, API keys, session client tokens and webhook secrets. These rules apply to every integration.

Related: [guide for AI agents](https://esigncomply.com/agents.md) · [setup runbook](https://esigncomply.com/setup.md) · [project rules block](https://esigncomply.com/rules.md) · [API conventions](https://esigncomply.com/docs/api.md) · [index of all pages](https://esigncomply.com/llms.txt)

## The account and the agent

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.

## The rules

1. **A person creates the account, once.** They enter their email, accept the terms and type the 6-digit code from their inbox. An agent never ticks the acceptance box and never types the code for them.
2. **The agent token is the agent's own credential.** The person creates it under "Agent access" (https://esigncomply.com/dashboard/agent). It acts as that person with their role, expires after 1, 7, 30 or 90 days, and can be revoked at any time. It is shown once and only its SHA-256 hash is stored.
3. **API keys are secret and server-only.** They are used only in server code: route handlers, server actions, background jobs. There are no publishable keys.
4. **Browsers hold only the session client token.** `POST /v1/sessions` returns `client_token` (`esc_ct_...`). It is short-lived, scoped to one session, and kept in memory by the browser SDK. It is the only Esign Comply credential that reaches client code.
5. **Never print or commit a credential.** Not in logs, error messages, URLs, test fixtures, screenshots, commit messages or chat.
6. **Get keys yourself, with the agent token.** `POST /v1/agent/api-keys` issues a key, and so does the dashboard. Without an agent token, the person puts the key in the environment themselves: never ask for a key in chat.
7. **Rotate on exposure.** If a token or a key was seen by anyone or anything that should not have it, revoke it and create a new one. Do this first, then investigate.

## Environment variables

| Variable | Holds | Where |
|---|---|---|
| `ESIGNCOMPLY_AGENT_TOKEN` | The agent token (`esc_agent_...`) | The project's server-side env file (`.env.local`), or the agent's own environment. Application code never reads it. |
| `ESIGNCOMPLY_API_KEY` | A secret API key. Test key in development and preview, live key in production. | Server environment only |
| `ESIGNCOMPLY_API_URL` | The API base URL: the `api_url` value of `GET /v1/agent`. The Node SDK and the CLI read it. | Server environment |
| `ESIGNCOMPLY_WEBHOOK_SECRET` | The signing secret of a webhook endpoint (`whsec_...`) | Server environment only |

- Never use a public prefix: not `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`, `REACT_APP_` or `EXPO_PUBLIC_`. A variable with such a prefix is compiled into the browser bundle.
- Local development: `.env.local`, listed in `.gitignore`.
- Hosted environments: the platform's environment variable or secret settings. Use the test key for preview and development and the live key for production only.
- The agent token is for the agent. Keep it in the server-side env file next to the key, never in client code, a commit or a log. The application itself uses `ESIGNCOMPLY_API_KEY` and never reads the token.
- In a Next.js application, create the client in one module that starts with `import "server-only";` so that the build fails if a client component imports it.

```ts
// lib/esigncomply.ts
import "server-only";
import { EsignComply } from "esigncomply";

export const esc = new EsignComply(process.env.ESIGNCOMPLY_API_KEY!);
```

## Credential formats

| Credential | Format | Notes |
|---|---|---|
| Agent token | `esc_agent_...` (53 characters) | Opens a dashboard session at https://esigncomply.com/agent-login and authenticates https://esigncomply.com/v1/agent. Not accepted by the rest of the API. |
| Test key | `esc_test_us_...`, `esc_test_eu_...` | Works on `localhost`, `127.0.0.1` and listed preview hosts. No domain verification needed. |
| Live key | `esc_live_us_...`, `esc_live_eu_...` | Works once the domain is verified. On the Free plan it is created at go-live with no checkout. |
| Session client token | `esc_ct_...` | Returned by `POST /v1/sessions`. Browser only. Expires with the session. |
| Webhook secret | `whsec_...` | One per webhook endpoint |

A token or a key is shown once, when it is created. Esign Comply stores only a prefix and a SHA-256 hash. A lost one cannot be recovered: create a new one. Each key is bound to one domain and one region.

## What the agent token can do

In a browser, log in at https://esigncomply.com/agent-login: field "Agent token", button "Log in". Without a browser, send it as `Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN`:

| Call | What it does |
|---|---|
| `GET /v1/agent` | The organization, the domain with its DNS record, plan, usage, the next step and `api_url` |
| `POST /v1/agent/api-keys` | Issues an API key. Body: `{ "mode": "test" }` or `{ "mode": "live" }`. The key is returned once. |
| `GET /v1/agent/domain`, `PUT /v1/agent/domain` | Reads the domain, or registers one: `{ "domain": "app.example.com" }` |
| `POST /v1/agent/domain/verify` | Looks for the verification record now |
| `POST /v1/agent/go-live` | Saves the organization details and creates the live key on the Free plan |

Request and response bodies: https://esigncomply.com/docs/api/agent.md

- The token acts as the person who created it, in their organization, with their role. Every action is in the audit log under the token's ID.
- A revoked or expired token is refused on its next request, in the browser and through the API.
- A step that is the person's is refused with "This step needs the account owner in person." When the person has a second factor, the actions it protects are theirs as well.
- 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.

## Permissions of API keys

Give each key the least it needs.

| Permission | Use it for |
|---|---|
| `recording_access` | The application server. Creates sessions and reads record status and receipts for server confirmation. Cannot download evidence reports, evidence packages or certificates, and can never incur a certificate charge. This is the default for a new key. |
| `read_only` | Reporting and audit tools. Reads records, evidence, certificates and usage. Creates nothing. |
| `full_access` | Administration: profiles, domains, keys, webhooks, certificates, adoption. Keep it out of the application runtime where you can. |

## What an AI agent does when it needs a key

1. Check whether `ESIGNCOMPLY_API_KEY` is set, without printing its value.
2. If it is not set and you hold an agent token: `POST /v1/agent/api-keys` with `{ "mode": "test" }`, then store the key in `.env.local` or the platform's secret settings.
3. If you hold no agent token: say so, and ask your person to create one under "Agent access", or to put a test key in the environment themselves. Wait.
4. Verify the key with `GET /v1/usage`. Report only success or the error code.
5. Develop with the test key. The live key goes into the production environment only.

```bash
# Reports whether the variable is set, never its value.
test -n "$ESIGNCOMPLY_API_KEY" && echo "ESIGNCOMPLY_API_KEY is set" || echo "ESIGNCOMPLY_API_KEY is missing"
```

## Keep keys out of client code

- No file marked `"use client"` imports `esigncomply` or reads `ESIGNCOMPLY_API_KEY`.
- The browser calls your own server route to start a ceremony. That route returns `client_token` and nothing else that is secret.
- Do not proxy `@esigncomply/browser` calls through your server: the SDK sends ceremony events from the signer's device straight to Esign Comply.
- The server SDK refuses to construct in a browser.

Checks to run before you report success:

```bash
# No credential in the repository.
git grep -nE "esc_(test|live)_(us|eu)_[0-9A-Za-z]{8,}|esc_agent_[0-9A-Za-z_-]{8,}|whsec_[0-9A-Za-z+/=]{8,}" -- . ':!*.md' || echo "no credentials in tracked files"

# No key material in the built client bundle (Next.js).
grep -rEl "esc_(test|live)_(us|eu)_[0-9A-Za-z]{8,}" .next/static 2>/dev/null || echo "no keys in the client bundle"
```

## If a credential is exposed

1. Revoke it. An API key: in the dashboard, or `DELETE /v1/api-keys/{id}` with a `full_access` key. An agent token: the person presses "Revoke" under "Agent access".
2. Create a new one and update the environment variable everywhere it is set.
3. Redeploy.
4. Review the request log and the audit log in the dashboard for calls you did not make.
5. If it was committed, remove it from the repository history as well. Revoking comes first: a credential in history is exposed whether or not the commit is later removed.

Records already sealed are not affected by a revoked key. A leaked `recording_access` key cannot export stored evidence.

## Webhook secrets

Verify every delivery with the endpoint's secret before acting on it, and reject timestamps more than 5 minutes old. See https://esigncomply.com/docs/api/webhooks.md. Rotate a webhook secret the same way as a key if it is exposed.
