Agent account API
The account API for AI agents. With an agent token an agent reads the account state, creates API keys, registers and verifies the domain and goes live on the Free plan.
The account API is for an AI agent that works for a person. The person creates the account and accepts the terms once. After that the agent does everything: create keys, register documents, build the flow, verify the domain, go live. These endpoints cover the part an API key cannot reach, the account itself. With the API key they issue, the agent uses the rest of the API on the other pages.
The same steps exist in the dashboard, which an agent opens with the same token at https://esigncomply.com/agent-login. The labels of every page are in the guide for AI agents.
| Method and path | Purpose |
|---|---|
GET /v1/agent |
The account state and the next step. |
POST /v1/agent/api-keys |
Create a test key or a live key. The key is returned once. |
GET /v1/agent/domain |
The domain and the DNS record that verifies it. |
PUT /v1/agent/domain |
Register the domain. |
POST /v1/agent/domain/verify |
Look for the verification record now. |
POST /v1/agent/go-live |
Save the organization's details and create the live key on the Free plan. |
Authentication
Send an agent token as a Bearer token. It is not an API key and it works on these endpoints only.
curl -s https://esigncomply.com/v1/agent \
-H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN"
- Where the token comes from. A signed-in person creates it in the dashboard under Agent access (
/dashboard/agent), button "Create agent token". A new account lands on that page when sign-up starts athttps://esigncomply.com/signup?next=/dashboard/agent. An agent that drives the person's logged-in browser presses the button itself. Otherwise the person pastes the token to the agent. - Format.
esc_agent_followed by 43 characters. It is shown once and only its SHA-256 hash is stored. - What it is. It acts as the member who created it, with that member's role, in that member's organization, on the organization's first domain. It expires after 1, 7, 30 or 90 days and can be revoked at any time under Agent access. A revoked or expired token is refused on its next request.
- Where to keep it. In
ESIGNCOMPLY_AGENT_TOKEN, in the project's server-side env file or the agent's own environment. Never in client code, a URL, a log or a commit. See /auth.md. - Audit. Every change made through these endpoints is in the organization's audit log under the token's ID.
Authentication failures use 401:
| Code | Message | What to do |
|---|---|---|
missing_api_key |
"Send your agent token in the Authorization header: Bearer esc_agent_…" | Add the header. |
invalid_api_key |
"That is not a valid agent token. Paste the whole token: it starts with esc_agent_ and is 53 characters long." | Check the variable holds the whole token. |
invalid_api_key |
"This agent token has expired. Ask the account owner to create a new one under Agent access in the dashboard." | Ask the person for a new token. |
invalid_api_key |
"This agent token was revoked. Ask the account owner to create a new one under Agent access in the dashboard." | Ask the person for a new token. |
invalid_api_key |
"This endpoint takes an agent token (esc_agent_…), not an API key. API keys work on every other /v1 endpoint." | Send the agent token here and the API key everywhere else. |
Rate limits
60 calls a minute for each token, and 120 calls a minute for each address. Past either, the answer is 429 rate_limit_exceeded with a Retry-After header in seconds. Wait that long and send the request again.
What stays with the person
The token cannot do these, here or in the dashboard:
- Create the account: the email, the acceptance of the terms, and the 6-digit code from the person's inbox.
- Accept legal terms or sign anything for the organization.
- Change sign-in security: second factors.
- Create agent tokens. An agent can revoke its own.
- Manage team members and roles.
- Change billing or the plan.
A refused step answers 403 insufficient_permission and the message ends with "This step needs the account owner in person. An agent session cannot do it. Ask the person to log in at /login and do it themselves." The error carries needs_person: true. Tell the person which step it was and carry on with the rest.
Two more cases use the same code. The member's role does not allow the call, for example a viewer creating a key. Or the member has a second factor and the call is one it protects: replacing a domain that is already registered.
Get the account state
GET /v1/agent
One call tells the agent where the account stands: the organization, the domain with its DNS record, the plan and usage, how far setup is, and the next step with its API call and its dashboard page. It reads only, and it is the one call a locked account still answers.
curl -s https://esigncomply.com/v1/agent \
-H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN"
A new account, straight after sign-up:
{
"object": "agent_account",
"token": { "id": "agt_3wpK07ihU8BUsiVPjYNG", "name": "My AI agent", "expires_at": "2026-12-22T20:06:04.267Z" },
"acts_as": { "email": "dana@example.com", "role": "owner", "second_factor_enrolled": false },
"organization": { "id": "org_6d42EAR0VSSYmodPnQ6x", "name": "example.com", "legal_name": null, "country": null, "details_complete": false },
"domain": {
"object": "domain",
"id": "dom_5tJCGkyXZgQ61mbmPPV5",
"domain": null,
"entered_host": null,
"region": "us",
"status": "not_started",
"verification": null,
"registered_at": null,
"verified_at": null,
"last_checked_at": null,
"lapsed_at": null,
"test_origins": [],
"api_url": "https://esigncomply.com/v1",
"created_at": "2026-11-22T20:06:04.241Z"
},
"plan": { "id": "sandbox", "name": "Free", "status": "active", "live_events": 10, "live_events_period": "month", "test_events_per_month": 500 },
"usage": {
"object": "usage",
"plan": "sandbox",
"plan_name": "Free",
"events": {
"used": 0,
"quota": 10,
"period": "month",
"period_start": "2026-11-01T00:00:00.000Z",
"resets_at": "2026-12-01T00:00:00.000Z",
"open_sessions": 0,
"allowance": 10,
"remaining": 10,
"level": "ok",
"locked": false,
"locked_since": null
},
"test_events": { "used_this_month": 0, "quota_per_month": 500 }
},
"locked": null,
"live": {
"ready": false,
"live": false,
"live_keys": 0,
"test_keys": 0,
"agreements_accepted": true,
"blockers": [
{ "code": "domain_not_verified", "message": "Register and verify your domain first. Live keys only work on a verified domain." },
{ "code": "organization_details", "message": "Add your organization's legal name and country first. The legal name is printed on every evidence report." }
],
"allowance": { "limit": 10, "used": 0, "open_sessions": 0, "remaining": 10, "resets_at": "2026-12-01T00:00:00.000Z", "locked": false },
"domain_verified": false,
"needs_person": false
},
"onboarding": { "key_created": false, "first_test_record": false, "domain_verified": false, "live": false },
"next_step": {
"id": "create_test_key",
"done": false,
"what": "Create a test API key and store it server-side as ESIGNCOMPLY_API_KEY.",
"api": "POST /v1/agent/api-keys {\"mode\":\"test\"}",
"browser": "/dashboard"
},
"steps": [
{ "id": "create_test_key", "done": false, "what": "Create a test API key and store it server-side as ESIGNCOMPLY_API_KEY.", "api": "POST /v1/agent/api-keys {\"mode\":\"test\"}", "browser": "/dashboard" },
{ "id": "register_domain", "done": false, "what": "Register the domain the signing pages run on.", "api": "PUT /v1/agent/domain {\"domain\":\"example.com\"}", "browser": "/dashboard/domains" }
],
"human_only": [
"Accepting legal terms or signing anything for the organization",
"Sign-in security: second factors",
"Creating agent tokens (an agent can revoke its own)",
"Team members and roles",
"Billing and plan changes"
],
"api_url": "https://esigncomply.com/v1",
"dashboard_url": "https://esigncomply.com/dashboard",
"agent_login_url": "https://esigncomply.com/agent-login",
"guide_url": "https://esigncomply.com/agents.md"
}
The example is shortened: usage is the whole object of GET /v1/usage, and steps has seven entries.
| Field | Meaning |
|---|---|
token |
The token in use: its ID, its name and when it expires. Never the token itself. |
acts_as |
The member the token acts as, their role, and whether they have a second factor. |
organization |
The organization. details_complete is true once the legal name and the country are saved. |
domain |
The domain object. verification holds the DNS record once a domain is registered. |
plan |
The plan: sandbox is the id of the Free plan. |
usage |
The object of GET /v1/usage. events.used against events.allowance is the count to watch. |
locked |
null, or the lock when the plan's limit was reached. See When the account is locked. |
live |
ready: a live key can be created now. live: ready and holding a live key. blockers lists what stands in the way, in the order to fix it. needs_person is true when a blocker is the person's step. |
onboarding |
The four steps of the dashboard's Get started page. |
next_step |
The first entry of steps that is not done, or the upgrade when the account is locked. api is the call to make and browser is the dashboard page for the same step. |
steps |
Every step in order: create_test_key, first_test_record, register_domain, verify_domain, organization_details, accept_agreements, create_live_key. |
human_only |
The steps that stay with the person. |
api_url |
The base URL of the API for this domain. Store it as ESIGNCOMPLY_API_URL: the Node SDK and the CLI read that variable. |
Create an API key
POST /v1/agent/api-keys
| Field | Type | Required | Meaning |
|---|---|---|---|
mode |
string | No | test (default) or live. |
name |
string | No | Up to 80 characters. Default: Agent: and the token's name for a test key, Production for a live key. |
A test key has full_access, like the key the dashboard creates on Get started. A live key has recording_access and exists once the domain is verified, the organization's details are saved and the agreements are recorded. The member's role must allow keys: owner or admin.
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" }'
201:
{
"object": "api_key",
"id": "key_PbwXhAWR8pXS1N9ofkh2",
"name": "Agent: My AI agent",
"livemode": false,
"permission": "full_access",
"prefix": "esc_test_us_Wxn3as…",
"key": "esc_test_us_Wxn3as…",
"env": "ESIGNCOMPLY_API_KEY",
"created_at": "2026-11-22T20:06:10.414Z"
}
key holds the whole key, once. It is shortened in this example. Store it on the server as ESIGNCOMPLY_API_KEY: the test key in development and preview, the live key in production only. Keep both out of the repository and out of client code.
A live key asked for too early answers with what is missing. 403 domain_not_verified:
{
"error": {
"type": "permission_error",
"code": "domain_not_verified",
"message": "Register and verify your domain first. Live keys only work on a verified domain.",
"blocker": "domain_not_verified",
"blockers": ["domain_not_verified", "organization_details"],
"next_step": "verify_domain",
"needs_person": false,
"doc_url": "https://esigncomply.com/docs/api/errors#domain_not_verified",
"request_id": "req_mp4DEbmfh5s7FZyRfEvhhVFm"
}
}
Register the domain
PUT /v1/agent/domain
| Field | Type | Required | Meaning |
|---|---|---|---|
domain |
string | Yes | A host or a URL, for example app.example.com. The registrable domain is worked out from it, and one registration covers every subdomain. |
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" }'
200, the domain object:
{
"object": "domain",
"id": "dom_5tJCGkyXZgQ61mbmPPV5",
"domain": "example.com",
"entered_host": "app.example.com",
"region": "us",
"status": "pending",
"verification": {
"method": "dns",
"type": "TXT",
"name": "_esigncomply.example.com",
"host": "_esigncomply",
"value": "esc-verify=HtWZeL5x6k7RqLtryag68NqZf0BGg3oL"
},
"registered_at": "2026-11-22T20:06:10.502Z",
"verified_at": null,
"last_checked_at": null,
"lapsed_at": null,
"test_origins": [],
"api_url": "https://esigncomply.com/v1",
"created_at": "2026-11-22T20:06:04.241Z"
}
Publish the TXT record in verification at the DNS provider: name, type and value. An agent with access to the DNS provider adds it. An agent without access gives the person those three values and asks them to add that one record. A host on a platform address such as myapp.vercel.app gets "method": "file" with a url and a content instead: a file the agent adds to the app.
GET /v1/agent/domain returns the same object at any time. The member's role must allow domain changes: owner or admin. Registering the first domain is an ordinary step. Replacing a registered domain with another is a domain change: it is allowed once in 12 months, and when the member has a second factor it needs the person.
Verify the domain
POST /v1/agent/domain/verify
No body. Two public resolvers are asked for the record, and both must return the value.
curl -s -X POST https://esigncomply.com/v1/agent/domain/verify \
-H "Authorization: Bearer $ESIGNCOMPLY_AGENT_TOKEN"
200, the domain object with two more fields. Before the record is visible:
{
"object": "domain",
"id": "dom_5tJCGkyXZgQ61mbmPPV5",
"domain": "example.com",
"entered_host": "app.example.com",
"region": "us",
"status": "pending",
"verification": {
"method": "dns",
"type": "TXT",
"name": "_esigncomply.example.com",
"host": "_esigncomply",
"value": "esc-verify=HtWZeL5x6k7RqLtryag68NqZf0BGg3oL"
},
"registered_at": "2026-11-22T20:06:10.502Z",
"verified_at": null,
"last_checked_at": "2026-11-22T20:06:10.601Z",
"lapsed_at": null,
"test_origins": [],
"api_url": "https://esigncomply.com/v1",
"created_at": "2026-11-22T20:06:04.241Z",
"verified": false,
"check": {
"method": "dns",
"ok": false,
"detail": {
"name": "_esigncomply.example.com",
"expected": "esc-verify=HtWZeL5x6k7RqLtryag68NqZf0BGg3oL",
"cloudflare": [],
"google": [],
"cloudflare_ok": false,
"google_ok": false
}
}
}
verified is true and status is verified once both resolvers return the value. A record published a moment ago can take a few minutes to reach both, so wait and call again. The check also runs on its own: every minute for the first hour after registration, then every 15 minutes for 72 hours.
Go live on the Free plan
POST /v1/agent/go-live
Going live on Free takes a verified domain and the organization's details. There is no plan to choose, no card and no checkout. The terms and the Data Processing Agreement were accepted at sign-up.
| Field | Type | Required | Meaning |
|---|---|---|---|
organization |
object | No | The organization's details. Saved first when sent. Needed once: leave it out when they are on file. |
organization.legal_name |
string | Yes | The legal entity. It is printed on every evidence report. |
organization.country |
string | Yes | ISO 3166-1 alpha-2, for example US. |
organization.line1, organization.city |
string | Yes | The registered address: street and city. |
organization.billing_email |
string | Yes | Where billing mail goes. |
organization.line2, region, postal_code, state, tax_id |
string | No | The rest of the address, the ISO 3166-2 state code, and a tax ID. |
key_name |
string | No | Name of the live key. Default Production. |
new_key |
boolean | No | true creates another live key on an account that already has one. |
Ask the person for the organization's details. Do not guess them.
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" } }'
201 when the live key was created:
{
"object": "go_live",
"live": true,
"created": true,
"api_key": {
"object": "api_key",
"id": "key_j4TWSQMqVSaj14wnU03c",
"name": "Production",
"livemode": true,
"permission": "recording_access",
"prefix": "esc_live_us_78nWnn…",
"key": "esc_live_us_78nWnn…",
"env": "ESIGNCOMPLY_API_KEY"
},
"status": {
"plan": "sandbox",
"plan_name": "Free",
"free": true,
"domain": { "id": "dom_5tJCGkyXZgQ61mbmPPV5", "name": "example.com", "status": "verified", "region": "us", "verified": true },
"organization": { "complete": true, "legal_name": "Acme, Inc.", "country": "US" },
"agreements": { "accepted": true, "missing": [], "accepted_at": "2026-11-22T20:06:10.694Z", "record_id": "rec_SHmGZ9sarsqjgU8rTihX" },
"live_keys": 1,
"ready": true,
"live": true,
"blockers": [],
"next_step": "done",
"allowance": { "limit": 10, "used": 0, "open_sessions": 0, "remaining": 10, "resets_at": "2026-12-01T00:00:00.000Z", "locked": false }
}
}
api_key.key holds the whole live key, once. It is shortened in this example. Set it as ESIGNCOMPLY_API_KEY in the production environment only. Test and live share nothing: copy the test documents and profiles to live in the dashboard (Go live, "Copy test setup to live"), or create them again with the live key.
A second call on an account that is live answers 200 with "created": false and "api_key": null. It creates no further key unless new_key is true.
When something stands in the way, the error names it in blocker and next_step:
| Status and code | blocker |
What to do |
|---|---|---|
403 domain_not_verified |
domain_not_verified |
Register and verify the domain. |
400 invalid_request, param organization |
organization_details |
Send organization. |
403 insufficient_permission, needs_person: true |
agreements |
An account created before the Data Processing Agreement joined the sign-up acceptance. The person accepts once on the Go live page of the dashboard. |
403 insufficient_permission, needs_person: true |
subscription_canceled, region_not_on_plan, free_domain_taken |
A plan matter. The person settles it under Settings, Billing. |
The refusal for the acceptance, as returned:
{
"error": {
"type": "permission_error",
"code": "insufficient_permission",
"message": "The customer terms and the data-processing agreement have not been accepted for this organization yet. The account owner accepts them once on the Go live page. This step needs the account owner in person. An agent session cannot do it. Ask the person to log in at /login and do it themselves.",
"blocker": "agreements",
"blockers": ["agreements"],
"next_step": "accept_agreements",
"needs_person": true,
"doc_url": "https://esigncomply.com/docs/api/errors#insufficient_permission",
"request_id": "req_jmaZMby2eiUawoct9EQeBe4B"
}
}
When the account is locked
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.
Starter covers 2,000 live signature events a year. At 2,000 the account locks until you pay: upgrade to Unlimited, add an event pack, or renew. Past the limit, new live signatures can be refused, so upgrade before you get there.
Watch usage.events.used against usage.events.allowance in GET /v1/agent, or the same fields of GET /v1/usage, and tell the person before the limit is reached. Upgrading is the person's step.
On a locked account GET /v1/agent still answers. locked holds the lock, with no reset date, and next_step is the upgrade:
{
"locked": {
"locked": true,
"since": "2026-11-22T20:06:10.818Z",
"plan": "sandbox",
"plan_name": "Free",
"domain": "example.com",
"limit": 10,
"used": 10,
"period": "month",
"upgrade_url": "https://esigncomply.com/dashboard/settings/billing",
"message": "This account is locked: all 10 of the live signatures the Free plan covers in a month are used. It stays locked until you upgrade to a paid plan. It does not unlock at the start of the next month. That step is the account owner's: https://esigncomply.com/dashboard/settings/billing."
},
"next_step": {
"id": "upgrade",
"done": false,
"what": "This account is locked: all 10 of the live signatures the Free plan covers in a month are used. It stays locked until you upgrade to a paid plan. It does not unlock at the start of the next month. That step is the account owner's: https://esigncomply.com/dashboard/settings/billing.",
"api": null,
"browser": "/dashboard/settings/billing"
}
}
Only the two fields that change are shown. used is a true count and can be higher than limit.
Every other call on this page answers 402 quota_exhausted and changes nothing:
{
"error": {
"type": "quota_error",
"code": "quota_exhausted",
"message": "This account is locked: all 10 of the live signatures the Free plan covers in a month are used. It stays locked until you upgrade to a paid plan. It does not unlock at the start of the next month. That step is the account owner's: https://esigncomply.com/dashboard/settings/billing.",
"locked": true,
"locked_since": "2026-11-22T20:06:10.818Z",
"plan": "sandbox",
"plan_name": "Free",
"limit": 10,
"period": "month",
"upgrade_url": "https://esigncomply.com/dashboard/settings/billing",
"doc_url": "https://esigncomply.com/docs/api/errors#quota_exhausted",
"request_id": "req_v988F1oWggTA3JR5R5ob32JV"
}
}
Do not retry in a loop: the lock does not lift on its own. Tell the person, and give them upgrade_url. The dashboard shows the same in an agent session: the lock screen and the billing page, and nothing else.
Errors
Errors use the envelope of the whole API: error.type, error.code, error.message, error.doc_url and error.request_id. See error codes.
| Status | Code | When |
|---|---|---|
400 |
invalid_request |
A field is missing or malformed. param names it. |
401 |
missing_api_key, invalid_api_key |
No token, or a token that is wrong, expired or revoked. |
402 |
quota_exhausted |
The account is locked. |
403 |
insufficient_permission |
The step is the person's, or the member's role does not allow it. |
403 |
domain_not_verified |
A live key was asked for before the domain is verified. |
409 |
domain_already_registered |
Another organization holds the domain. |
429 |
rate_limit_exceeded |
Too many calls. Wait for Retry-After. |