# eDocInk agent guide: connect an application

This guide is written for AI coding agents (and the developers working with them). Follow
it step by step to add document signing to an application through the eDocInk API. It
summarises the [integration requirements](https://edocink.com/guides/integration-requirements.md)
and the [API reference](https://edocink.com/guides/api-reference.md); where they differ,
those two documents win. The machine-readable contract is
[openapi.json](https://edocink.com/openapi.json).

## Quick start: the smallest safe integration

For a small app with one signer per document, this is all you need. Everything after it
in this guide adds robustness (webhooks, several signers, full recovery) you can grow into.

1. **Store three things** in your database: each POST's idempotency key (written before
   you send), the `original_sha256` of the prepared document, and the SHA-256 of each
   signing link's `invitation` parameter.
2. **Send:** prepare the text, create the request, create an invitation and read its
   hand-off (section 4, steps 2 to 4). You get a `signing_url`.
3. **Deliver** the link yourself: an email from your app, or a button on your own page.
4. **Check:** when the signer comes back to your app, or on a timer, call
   `GET /api/v1/requests/{id}` until it is `signed` and its completion is `ready`. No
   webhook endpoint is needed.
5. **Verify:** fetch the evidence and verify it (section 7). In Node, that is one call to
   the SDK's `verifyGuestPlainTextEvidence`. Only then mark the document signed.

You can skip webhooks, the event feed, envelopes and templates. Do not skip
idempotency keys or evidence verification: they are what make the result trustworthy.

## 0. Rules you must not break

- The API key is a **server-side secret**. Never put it in browser or mobile code, logs,
  test snapshots, commits or prompts. Load it from the app's secret store.
- **Save every idempotency key before sending its POST.** After a timeout, recover with
  the same key. Never invent a new key to "try again".
- **Do not treat a document as signed until its evidence verifies** against pinned public
  keys and the app's own records.
- Signing links grant access to sign. Store them only as long as needed to deliver them,
  and never log them.
- eDocInk sends **no email**. The application delivers each signing link itself.

## 1. Ask the human for these (do not guess them)

If the developer has no credentials yet, request them on their behalf with
`POST https://edocink.com/api/access` (see [Get access](https://edocink.com/access.md)),
using **their** email address, and tell them to open the confirmation email. Guest-signing
credentials then arrive in their inbox, usually within a few minutes; they are shown to
them once and you never see them unless they put them in configuration. Keep building
against the contract meanwhile. Ask the developer for the values they received, and store them as
server-side configuration:

| Setting | Example | Secret? |
| --- | --- | --- |
| `EDOCINK_ORIGIN` | the sandbox base URL they were given | no |
| `EDOCINK_APP_ID` | uuid | no |
| `EDOCINK_TENANT_ID` | uuid, sent as `X-Tenant-ID` | no |
| `EDOCINK_API_KEY` | bearer key | **yes** |
| `EDOCINK_POLICY` | `guest@1` (name and version) | no |
| `EDOCINK_EVIDENCE_PUBLIC_KEYS` | JSON map of key id → Ed25519 public key | no, but pinned |
| `EDOCINK_WEBHOOK_KEYS` | key id → secret, only if webhooks are configured | **yes** |

Also ask: who signs (one person, or several who must all sign), how the app will reach
signers (its email provider or an in-app inbox), and whether the app has a public HTTPS
endpoint for webhooks. If you cannot get credentials, build against the contract and
leave the integration switched off.

## 2. Choose a client

- **Node 24+:** use the SDK `@esign/integration-hooks` (an archive; email
  info@edocink.com for it, it is not in the credentials email). It implements idempotent calls, recovery, webhook verification
  (`receiveWebhookOnce`) and evidence verification (`verifyGuestPlainTextEvidence`,
  `verifyGuestEnvelopeEvidence`, `verifyPdfEvidence`). Prefer it. Call
  `checkCompatibility()` at startup and log what it says; the SDK also logs each new
  notice from eDocInk once.
- **Any other language:** call the HTTPS API directly from
  [openapi.json](https://edocink.com/openapi.json), and implement evidence verification
  with an Ed25519 and SHA-256 library, following section 9 of the integration
  requirements.

Every call sends:

```
Authorization: Bearer $EDOCINK_API_KEY
X-Tenant-ID: $EDOCINK_TENANT_ID
Content-Type: application/json        (on POST)
Idempotency-Key: <saved key>          (on every POST)
```

## 3. Add storage first

Create these records in the application's own database (names are suggestions):

- `signature_requests`: app record id, eDocInk preparation id, request id, status,
  `original_sha256` and the exact inputs sent, latest `resource_version`.
- `signature_operations`: one row per POST with its idempotency key, written **before**
  the POST is sent, and its outcome after.
- `signature_links`: request id, signer, invitation key, the **SHA-256 of the link's
  `invitation` query parameter**, expiry. Keep every digest ever issued for a signer.
- `signature_events`: processed webhook `Esign-Event-ID`s, or the event-feed cursor.
- `signature_evidence`: the verified evidence bundle.

## 4. Send a document to one signer

1. `GET /api/v1/signing-policies` and check the configured policy is listed.
2. `POST /api/v1/text-document-preparations` with:

   ```json
   {
     "policy": {"name": "guest", "version": 1},
     "document": {"title": "Service agreement", "body": "The full text to be signed."},
     "recipient": {"email": "pat@example.com", "display_name": "Pat Example"},
     "expires_in": 604800
   }
   ```

   Optional: `business_reference` (up to 200 characters) to link it to your record.
   The response's `text` is exactly what will be signed and `original_sha256` is its
   hash. Store both. A preparation expires after 10 minutes.
3. `POST /api/v1/document-preparations/{preparation_id}/requests` with body `{}`. The
   request starts `preparing` and becomes `pending` within a second or two.
4. `POST /api/v1/requests/{request_id}/invitations` with body `{}` and a new invitation
   key. Then `GET /api/v1/requests/{request_id}/invitation-handoff` with header
   `X-Original-Invite-Key: <that key>`. The response has `signing_url` and `expires_at`.
   A **409** means the request is still preparing: wait briefly and repeat the same GET.
5. Record the SHA-256 of the `invitation` query parameter of `signing_url`, then deliver
   the link to the signer. Links last 72 hours (never beyond the request) and work once;
   opening one starts a 15-minute signing session.

## 5. Several signers who must all sign

`POST /api/v1/envelope-preparations` with the document and 2 or more signers (each with
`slot_id`, `role` and `recipient`), then `POST /api/v1/envelope-preparations/{id}/envelope`,
then `POST /api/v1/signing-envelopes/{id}/invitations` and its `invitation-handoff` for one
link per signer. Track with `GET /api/v1/signing-envelopes/{id}` and verify the evidence for
every member request once it is complete.

## 6. Learn what happened

- **Event feed (always available):** `GET /api/v1/events?after=<cursor>&limit=100`.
  Save the cursor after each page.
- **Webhooks (optional):** verify `Esign-Signature` as HMAC-SHA256 over
  `<Esign-Timestamp>.<Esign-Delivery-ID>.<raw body>` in constant time, reject timestamps
  more than 5 minutes off, skip event ids already processed, answer 2xx within 10 seconds.

Treat each event as a prompt to re-read the request (`GET /api/v1/requests/{id}`) and act
on its current state.

## 7. Verify evidence before marking anything signed

When the request is `signed` and its completion is `ready`, call
`GET /api/v1/requests/{id}/evidence` and verify:

- the Ed25519 signature against the **pinned** public keys (never keys from the bundle);
- the document hash against the stored `original_sha256`;
- the policy and consent against what the app chose;
- for guest links, `credential_digest` against **one of the link digests the app recorded**
  for that signer.

Only then mark the document signed and store the bundle. If anything fails, do not mark it
signed; flag it for a person.

## 8. Handle errors by status code

| Status | Do this |
| --- | --- |
| 400, 413, 415 | Fix the request; do not retry unchanged |
| 401 | Key unknown, expired or revoked: stop and tell the human |
| 403 | Key lacks a scope: tell the human |
| 404 after a timeout | Inconclusive: recover with the original key |
| 409 | Not ready or not allowed in this state: re-read, then retry only if it can change |
| 410 | Cursor expired: restart the scan and reconcile |
| 412, 428 | Re-read and send the current `If-Match` |
| 429, 503 | Wait for `Retry-After`, retry with the same key |

## 9. Prove it works in the sandbox

Write tests (against the sandbox, never production) that show:

1. A document is prepared, sent, signed by following the link, and its evidence verifies.
2. A simulated timeout on each POST recovers the original result with no duplicate.
3. Reissuing a link makes the old link fail and the new one sign.
4. A tampered evidence bundle is refused.
5. The sixth link in an hour (429) and a still-preparing request (409) are handled.
6. Cancelling (`POST /api/v1/requests/{id}/cancel`) sends a fresh
   `If-Match: "<resource_version>"` from the latest read.

Then work through the go-live checklist in section 12 of the integration requirements and
hand the results to the human, who sends them to runMast for production access.

## 10. Tell us what went wrong

If a guide was unclear, wrong or missing something, or the API did not behave as described,
report it so the guides can be fixed for the next agent. Ask the human first if your
environment requires approval for outbound requests.

```
POST https://edocink.com/api/feedback
Content-Type: application/json

{
  "kind": "unclear",
  "page": "/agents#4-send-a-document-to-one-signer",
  "message": "What you expected, what happened, and what would have helped.",
  "contact": "",
  "agent": "the agent or tool name"
}
```

`kind` is one of `unclear`, `api`, `missing`, `agent` or `other`. `contact` is an optional
email for a reply. The answer is `202 {"status":"received"}`. **Never include API keys,
signing links, evidence bundles or real personal data.** People can use the form at
https://edocink.com/feedback.

## Where to find more

- Overview: https://edocink.com/index.md
- Access: https://edocink.com/access.md
- Integration requirements: https://edocink.com/guides/integration-requirements.md
- API reference: https://edocink.com/guides/api-reference.md
- OpenAPI 3.1 contract: https://edocink.com/openapi.json
- Changelog: https://edocink.com/changelog.md (feed: https://edocink.com/changelog.atom)
- Everything in one file: https://edocink.com/llms-full.txt
- Feedback: https://edocink.com/feedback
