# Integration requirements

What an application needs, and must do, to use the eDocInk service. Read this before the
[API reference](/guides/api-reference). It describes eDocInk API v1 (the OpenAPI contract's `info.version` versions this
documentation; the API itself is `/api/v1`). Some headers and schema names still say
`esign`/`Esign` from the product's earlier name; they are part of v1 and will not change.

## 1. What the service does, and what your app does

| The eDocInk service | Your application |
| --- | --- |
| Freezes the exact document text and its SHA-256 | Decides what the document says, and that the person sending it may send it |
| Hosts the signing pages: review, consent, signature | Decides who must sign, and gets each signing link to the right person |
| Shows each business's name, logo and colour on the signing pages (set by the operator) | Sends the operator the business's display name, accent colour and logo |
| Checks the signer's link (or account sign-in) and records consent | Sends the email or in-app message with the link (the service sends no email) |
| Tells you what happened: event feed and signed webhooks | Updates its own records when a document is signed, expires or is withdrawn |
| Produces signed evidence for each signature | Verifies that evidence against its own records and keeps it |
| Isolates every app and tenant from every other | Keeps its own keys secret and its own copies under its own retention rules |

The service never sees your database and you never see its database. Everything goes
through the HTTPS API.

**What the service does not do today:**
- send email;
- produce PDFs or rich layouts (documents are plain text or simple templates);
- send the signer back to your app after signing (the last page says they can close the
  tab; learn the outcome by webhook or event feed, see section 8);
- prove a guest signer's identity (an email link proves control of the link, nothing more).

## 2. Prerequisites

1. **A server-side component** that can make HTTPS calls and hold secrets. The API key
   must never reach a browser, mobile app or log.
2. **Durable storage** you control: a database table or two (see section 6).
3. **A way to reach signers**: an email provider or an in-app inbox.
4. **Either** the SDK (`@esign/integration-hooks`, Node 24+; it includes the evidence and
   webhook verifiers) **or** your own HTTPS client plus an Ed25519/SHA-256 library. The
   SDK is strongly recommended. It implements sections 6–9 for you. It is supplied as an
   archive on request (it is not part of the credentials); without it, section 9 gives
   the exact verification steps.
5. **Optional:** a public HTTPS endpoint for webhooks. Without one, poll the event feed.

## 3. Getting access

Ask the service operator for access with: app name, owner contact, expected volume, the
signing methods you need (guest email link, or account sign-in with your identity
provider), the consent wording, and your webhook URL if any.

You receive, privately, **per environment** (sandbox first, then production):

| Item | Use |
| --- | --- |
| `origin` | Base URL: `https://esign-sandbox.runmast.com` for the sandbox; production's is given with production access |
| `app_id`, `tenant_id` | Your app and tenant. Send the tenant as `X-Tenant-ID` on every call. |
| API key, its scopes and expiry | `Authorization: Bearer …`. Keys expire (at most 366 days). Rotate before expiry: the operator issues the new key, you deploy it, then the old one is revoked. |
| Signing policy name and version | Chosen per document, e.g. `{"name":"guest","version":1}`. The operator publishes it with the consent wording you agreed and the signing method. Policies are immutable; changes get a new version. |
| Evidence public keys | A map of key id to Ed25519 public key (unpadded base64url of the raw 32 bytes). Pin them in configuration; never fetch them from the evidence itself. |
| Webhook key id and secret (optional) | Verifies webhook signatures |

Scopes, by what you do: `documents:prepare` and `documents:submit` (prepare documents
and read policies), `requests:create`, `requests:read`, `invitations:create` (signing
links), `evidence:read`, `requests:cancel` (cancel/withdraw), `events:read` (event feed).

## 4. The calls, in order

### One signer

1. `GET /api/v1/signing-policies`: confirm the policy you will use is published.
2. `POST /api/v1/text-document-preparations` (or `/document-preparations` for a
   template): the service returns the **exact rendered text** and its `original_sha256`.
   Show this text to the person sending it if your workflow needs a review. What they
   see is byte-for-byte what will be signed. A preparation expires after 10 minutes.
3. `POST /api/v1/document-preparations/{id}/requests`: creates the signing request.
   It starts `preparing` and becomes `pending` once the service has frozen the
   document (normally a second or two).
4. `POST /api/v1/requests/{id}/invitations`: issue a signing link. Then
   `GET /api/v1/requests/{id}/invitation-handoff` with `X-Original-Invite-Key` returns
   the `signing_url`. A 409 here usually means the request is still `preparing`: wait
   briefly and retry the same GET.
5. Deliver the link (section 7).
6. Learn the outcome by webhook or `GET /api/v1/events` (section 8).
7. When the request is `signed` and its completion is `ready`: call
   `GET /api/v1/requests/{id}/evidence` and verify it (section 9).

Cancel with `POST /api/v1/requests/{id}/cancel` and
`If-Match: "<resource_version>"` from a fresh read.

### Several signers who must all sign (envelope)

1. `POST /api/v1/envelope-preparations` with the document and 2 to 20 signers (each with a
   `slot_id`, `role` and recipient).
2. `POST /api/v1/envelope-preparations/{id}/envelope`: creates one request per signer.
3. `POST /api/v1/signing-envelopes/{id}/invitations`, then
   `GET …/invitation-handoff`: one signing link per signer.
4. Track with `GET /api/v1/signing-envelopes/{id}` (`signed_count`, `complete`) or
   events. Fetch and verify evidence for each member request once complete.
5. To replace **one** signer's link, call the single-request
   `POST /api/v1/requests/{member_request_id}/invitations` with a new key. That revokes
   only that signer's earlier link.
6. Withdraw the whole envelope with `POST /api/v1/signing-envelopes/{id}/withdraw` and
   `If-Match: "<resource_version>"` (the version is in the body; envelopes send no ETag).

`POST /api/v1/signing-envelopes` (building an envelope from requests you already
created) is a low-level path. Each member request must have been created with
`business_reference` = `env:<sha256 of the canonical manifest>:<slot_id>`. Use the
prepared flow above unless you have a specific reason not to.

### A PDF document

A PDF follows the same steps; only the preparation differs.

1. `POST /api/v1/document-uploads` with the raw PDF as the body,
   `Content-Type: application/pdf`, up to 10 MiB (scope `documents:submit`). The service
   checks only that it looks like a PDF (`%PDF-` header, `%%EOF` trailer) and returns
   `{sha256, byte_length, media_type, expires_at}`. Uploading the same bytes again returns
   the same answer, so this call takes no `Idempotency-Key`; on a timeout, just upload
   again. An upload lasts 24 hours; at most 200 live uploads per app and tenant.
2. Check that `sha256` is the SHA-256 of the bytes you sent, and store it.
3. `POST /api/v1/pdf-document-preparations` with the same body as a plain-text
   preparation, except `document` is `{title, sha256}`. The response has `media_type`,
   `byte_length` and `original_sha256` (equal to the upload's `sha256`) and no `text`.
   For several signers, send `document: {title, sha256}` to
   `POST /api/v1/envelope-preparations` instead.
4. Continue at step 3 of the one-signer flow (or step 2 of the envelope flow).

The signer sees the PDF in their browser's own viewer on the signing page, with an
"Open the PDF in a new tab" link that works everywhere, including Android. They accept
the whole document; phase 1 has no signature boxes or form fields, and the service does
not stamp or sign the PDF itself. Your signing policies cover PDFs with no change.

`GET /api/v1/requests/{id}/original` (scope `requests:read`) returns the exact bytes the
signer reviewed, for text or PDF.

### Word, HTML, text or an image: convert it to PDF first

1. `POST /api/v1/document-conversions` with the raw file and its `Content-Type`: `.docx`,
   `.doc`, `.odt`, `.rtf`, `text/html`, `text/plain`, `image/png` or `image/jpeg`, up to
   10 MiB (scope `documents:submit`). The answer is `202` with an `id` and
   `status: "converting"`. Sending the same file again returns the same conversion, so this
   call takes no `Idempotency-Key`. At most 50 conversions per hour per app and tenant.
2. Poll `GET /api/v1/document-conversions/{id}` every second or two (a conversion normally
   takes under 10 seconds) until `status` is `ready` or `failed` (`reason` says why).
3. `GET /api/v1/document-conversions/{id}/pdf` and **look at the PDF before sending it**.
   It is what the signer will see and sign. Fonts and page breaks can differ from the
   program that made the file.
4. Prepare it as a PDF: `document: {title, sha256}` with the conversion's `pdf.sha256`, then
   continue as for any PDF.

The service converts in a sandbox with no network access, so remote images in HTML are not
loaded; embed images or use a PDF you render yourself. The evidence binds the PDF only; keep
your source file if you need it, linked by the conversion's `source_sha256`. Conversion is
off unless the operator enables it; until then the first call answers 503.

## 5. Idempotency and recovery (required)

- Every POST takes an `Idempotency-Key`. **Write the key to your database before you
  send the request.** If you crash or time out, you will know which key to recover with.
- Same key and same body: you get the original result, never a duplicate.
  Same key and a different body: 409.
- **Unknown outcome** (timeout, connection reset, 5xx): first ask with the matching
  read, which takes the original key: `GET …/document-preparations/{id}/requests` with
  `X-Original-Create-Key`, `GET …/invitations` with `X-Original-Invite-Key`, or
  `GET …/envelope-preparations/{id}` with `X-Original-Prepare-Key`. If nothing is found,
  retry the POST with the **same** key. Never mint a new key to "try again".
- A new signing link is the one case where you *want* a new key: each new invitation key
  issues a new link and revokes the previous one for that request.

## 6. What your app must store

| Record | Why |
| --- | --- |
| Each idempotency key, saved before its POST | Recovery without duplicates (section 5) |
| Request and envelope ids; for envelopes, the slot → request id map | Every later call |
| The prepared text's `original_sha256` and the inputs you sent | Evidence verification compares against these |
| **Every signing-link digest you issue, per signer** (SHA-256 of the link's `invitation` token) | Evidence records the digest of the link actually used. After a reissue it may be any of them. Verify against your own recorded set, never against a value taken from the evidence. |
| The latest `resource_version` you read | `If-Match` for cancel and withdraw |
| Processed webhook `Esign-Event-ID`s, or your event-feed cursor | Deduplication; resuming the feed |
| The verified evidence bundle | Your record of the signature |

Store signing links themselves only as long as you need to deliver them; they grant
access to sign.

## 7. Delivering signing links

- A link lives **72 hours** and never longer than the request. It works once: opening
  it starts a 15-minute signing session.
- **Optional "Continue" pattern:** email a link to *your* app. On GET, show a Continue
  button and change nothing, because email scanners open links. On POST, reuse the
  current link if the handoff still returns it; otherwise issue a new one with a new key
  and redirect to its `signing_url`.
- At most **5 links per signing request in any rolling hour** (the 6th is 429). A request
  has one signer, so this is also per signer. Each new link revokes the
  last one, and any open signing session with it.
- Tell signers who is asking and why. The signing page shows the document title, who
  requested it (tenant and app; with branding set, the tenant's name, colour and logo,
  otherwise a neutral "Document signing" heading), who
  the link was sent to, the document and the consent text.

## 8. Knowing what happened

- **Webhooks** (optional): POSTed to your HTTPS endpoint with `Esign-Event-ID`,
  `Esign-Delivery-ID`, `Esign-Timestamp`, `Esign-Key-ID` and `Esign-Signature`.
  To verify one:
  - Compute HMAC-SHA256 over `<timestamp>.<delivery id>.<raw body>`.
  - Compare it with the signature in constant time.
  - Reject timestamps more than 5 minutes off.
  - Ignore event ids you have already processed.
  - Answer 2xx within 10 seconds.

  Failed deliveries are retried for up to 72 hours. Order is not guaranteed. The SDK's
  `receiveWebhookOnce` does all of this.
- **Event feed**: `GET /api/v1/events?after=<cursor>&limit=100`, oldest first. Keep the
  cursor. It's always available, and is the fallback if webhooks are missed.
- There is no return URL: after signing, the signer is told they can close the tab. If
  your page waits for them, poll `GET /api/v1/requests/{id}` (every 5-10 seconds while
  they are signing, never faster) or listen for the webhook.
- Either way, treat an event as a prompt to re-read the request or envelope. Act on its
  current state.

## 9. Verifying evidence (required before you rely on a signature)

Evidence is a JSON bundle signed by the service with Ed25519. Before treating a document
as signed, verify the bundle with the SDK (`verifyGuestPlainTextEvidence`,
`verifyPlainTextEvidence`, or `verifyGuestPlainTextEnvelopeEvidence` for envelopes):

- its signature, against your **pinned** public keys;
- the document hash, against the `original_sha256` you stored;
- the policy and consent text, against what you chose;
- for guest links, `credential_digest` against **one of the link digests you recorded**
  for that signer.

For a PDF, use `verifyPdfEvidence(raw, expected, keys, pdfBytes)` with
`expected.document` set to `{title, sha256, byte_length}`; passing the PDF bytes makes it
check their hash too. For a guest PDF envelope, `verifyGuestEnvelopeEvidence({record,
envelope, invitationDigests, bundles, original: pdfBytes}, keys)` checks every member the
same way (SDK 0.33.0-alpha.1 or later). A converted PDF needs no separate upload: send the
conversion's `pdf.sha256` as `document.sha256` within 24 hours of creating the conversion.
Each member request keeps its own copy, which `GET /api/v1/requests/{id}/original` returns
after the conversion has expired. From the command line:
`python -m esign.evidence verify bundle.json --keys keys.json --original agreement.pdf`.

If anything does not match, do not treat the document as signed; investigate.

**Without the SDK.** Do every step; stop at the first failure. All hashes are lowercase hex
SHA-256.

1. Parse the bundle as strict JSON (UTF-8, at most 4 MiB) and keep the exact bytes you
   received.
2. `verification.algorithm` is `Ed25519` and `verification.key_id` equals
   `manifest.attestation_key_id` and is one of your pinned key ids.
3. Decode the pinned key (unpadded base64url, 32 bytes). SHA-256 of those raw 32 bytes
   equals `manifest.attestation_key_sha256`.
4. Canonicalise `manifest` with RFC 8785 (JCS). Its SHA-256 equals `manifest_sha256`.
   Every number in a manifest is an integer within ±2^53-1.
5. Decode `verification.signature` (unpadded base64url, 64 bytes). It is an Ed25519
   signature over the bytes `esign-evidence-v2` + one NUL byte (`0x00`) + the canonical
   manifest bytes, for guest bundles (`esign-evidence-v1` for account sign-in). It is not
   a signature over the `manifest_sha256` string.
6. `request_id`, app, tenant and recipient email are the ones you sent. The definition
   (`manifest.request.definition_name` and `definition_version`, repeated in
   `manifest.definition` and `manifest.acceptance.definition`) equals the `definition`
   returned when you created the request. For plain text it is a per-document name such
   as `submitted-text-…`, **not** your signing policy's name: the policy appears only by
   its content, in `manifest.request.frozen_policy.signing`.
7. The document hash: SHA-256 of the UTF-8 bytes of `title + "\n\n" + body`, exactly as
   returned at preparation, equals the `original_sha256` you stored and the
   `original_sha256` in the signature, review and acceptance. For a PDF it is the SHA-256
   of the PDF bytes you uploaded: `manifest.original` has `renderer_version` `pdf-v1`,
   `media_type` `application/pdf`, `sha256` and `byte_length`, and **no `content`** (the
   PDF is not inside the bundle). Check it against your own copy of the file.
8. `credential_digest` equals SHA-256 of the UTF-8 bytes of the `invitation` query
   parameter of a `signing_url` you issued for this request (record that digest when you
   receive each link).
9. `frozen_policy.signing.consent_version` and `consent_text` are the ones in your policy.
10. The audit-event hash chain, `manifest.audit_prefix`: three events, in order, from an
    app key, the worker and the signer session (`actor_kind` `app_key`, `worker`,
    `signer_session`). Start with `previous` set to 64 zeros. For each event:
    - `previous_hash` equals `previous`;
    - `event_hash` is the SHA-256 of the bytes of `previous` (as ASCII hex), then the
      base64-decoded `body_base64`, then the actor: the `actor_id` for the first
      event, `worker:` + `actor_id` for the second, `signer:` + `actor_id` for the
      third;
    - then set `previous` to `event_hash`.
11. `manifest.request.input_digest` is the SHA-256 of the request you sent: compact JSON
    with sorted keys and no ASCII escaping (`{"body":…,"method":"POST","path":…}`, UTF-8),
    where `body` is your create-request body and `path` is `/api/v1/requests` or
    `/api/v1/document-preparations/{id}/requests`. Only your app can recompute it, from
    the body it sent. It is plain sorted JSON, not RFC 8785.
12. The completion receipt, `manifest.completion`. `content` must equal exactly these
    fields copied from the manifest:
    - `schema_version`: `esign-completion-v2` for guest bundles, `esign-completion-v1`
      for account sign-in;
    - `scope`: `manifest.scope`;
    - `signature_id`, `signed_at`, `original_sha256`, `consent_version`,
      `declared_name`, `issuer`, `subject`: from `manifest.signature` (`signature_id` is
      its `id`);
    - `accepted_version`: `manifest.acceptance.resource_version`;
    - guest bundles only: `authentication_method`, set to `email-link`.

    `sha256` is the SHA-256 of the RFC 8785 bytes of `content`, and `byte_length` is the
    length of those bytes.

The SDK also checks that the timestamps are in order. If you skip any step, say so in
your own records.

**`completion_status: "building"` inside the bundle is expected.** `manifest.acceptance`
and the third audit event record the request as it was at the moment of signing, when
the completed record was still being built. The bundle you fetch is the result of that
build. Fetch it only once the request's completion is `ready`.

**Which environment signed it.** `manifest.attestation_key_id` names the key. The public
evidence keys for each environment, current and retired, are published at
`https://edocink.com/evidence-keys.json`. A bundle signed by a sandbox key comes from the
sandbox, where nothing signed is binding.

Keys are never removed from that list. A rotated key stays, marked `retired`, so old
evidence keeps verifying.

**Checking evidence you did not create.** Someone outside the app, such as an auditor, a
court expert or the signer, can check the signature (steps 2–5) against the published
keys rather than a key the app hands over. The document hash (step 7) and the timestamp
below need nothing from the app. Steps 6, 8, 9 and 11 compare against the app's own
records, so ask the app for them. The published list comes from eDocInk, so it is
independent of the app but not of eDocInk. The timestamp is the part that is independent
of both.

Evidence is the service's attestation. It is not a signed PDF. Its `assurance` text says
"no independent timestamp" because the bundle itself contains none; the independent
timestamp below is a separate document over the bundle's bytes.

**Independent timestamp (optional, recommended).** Shortly after evidence is ready, an
outside Time Stamp Authority timestamps the SHA-256 of the exact evidence bytes.
`GET /api/v1/requests/{id}/evidence/timestamp` returns it (409 until it exists, so
retry later; never hold up your own flow for it). Keep it with the evidence. To check
it, confirm `evidence_sha256` is the SHA-256 of the evidence bytes you stored, base64-decode
`response` to `timestamp.tsr`, and verify it with any RFC 3161 tool against the TSA root
you pinned (DigiCert Trusted Root G4, in the sandbox and production), for example
`openssl ts -verify -data evidence.json -in timestamp.tsr -CAfile tsa-root.pem`.
Use OpenSSL 3. The `openssl` built into macOS is LibreSSL, and it reports
`Verification: FAILED` for valid tokens. Install OpenSSL 3 with `brew install openssl@3`
and run `$(brew --prefix openssl@3)/bin/openssl`.
Get the root from DigiCert, not from the token or from eDocInk:
`https://cacerts.digicert.com/DigiCertTrustedRootG4.crt.pem`. It is also in the macOS,
Windows and Mozilla root stores. Its SHA-256 fingerprint is
`55:2F:7B:DC:F1:A7:AF:9E:6C:E6:72:01:7F:4F:12:AB:F7:72:40:C7:8E:76:1A:C2:03:D1:D9:D2:0A:C8:99:88`.
It proves the evidence existed no later than `gen_time`, independently of the service.
It does not prove who signed or that a signing took place. Anyone can timestamp any
bytes, so the timestamp only fixes when these exact bytes existed.

## 10. Errors and limits

Branch on the HTTP status, never on the message text.

| Status | Do this |
| --- | --- |
| 400, 413, 415 | Fix the request |
| 401 | The key is unknown, expired or revoked: rotate |
| 403 | The key lacks the scope: ask the operator |
| 404 | Not visible. After a timeout this is *inconclusive*, not proof of absence. |
| 409 | Not allowed in the current state (often "not ready yet"), or the same key with a different body. Re-read first. |
| 410 | A list or event-feed cursor expired, or the service history was restored: restart the scan and reconcile with your records |
| 412 / 428 | Re-read and send the current `If-Match` |
| 429, 503 | Wait for `Retry-After`; retry with the same key |

Limits:
- 5 links per signing request in any rolling hour.
- 100 unexpired preparations per app and tenant (each lasts 10 minutes), plus 100
  unexpired envelope preparations.
- 1,000 open requests (preparing or pending) per app and tenant, and 60 new requests per
  minute. Each envelope signer counts as one request. Ask the operator if you need more.
- 2 to 20 signers per envelope.
- Recipient email: a plain ASCII address such as `name@example.com`, with no display name.
- `expires_in` from 60 seconds to 30 days.
- Page size up to 100.
- Request bodies up to 1 MiB, except text and envelope preparations (2 MiB) and a PDF upload
  or conversion (10 MiB).
- Plain-text title up to 200 characters; the document (title, two newlines, body) up to
  200,000 UTF-8 bytes, about 30,000 words. Longer documents go as a PDF (413 tells you so).
  Evidence for a document over 10,000 characters needs SDK 0.31.0-alpha.1 or later.

### Staying current: notices and compatibility

The service tells your app about changes itself; you don't need to watch a mailing list.

- Every successful API response carries `eDocInk-Notices: <count>; latest="<id>"` while your
  app has notices it has not acknowledged. SDK 0.32 and later log one line per new notice.
- `GET /api/v1/notices` lists the notices that apply to your app, each with what changed,
  who it affects, what to do and, when an upgrade is involved, the minimum SDK. Which notices
  apply depends on the SDK version your app reports (SDK 0.32 sends
  `User-Agent: edocink-sdk/<version>`); an app that reports none sees every notice.
- `POST /api/v1/notices/{id}/acknowledge` marks one handled for the whole app. It is
  idempotent.
- `GET /api/v1/compatibility` returns the API version and whether your SDK is `current`,
  `supported` or `unsupported`. Call it at startup (`checkCompatibility()` in the SDK) and
  alert someone when it says to upgrade.
- While an operation you call, or the SDK version you report, is being retired, responses
  also carry `Deprecation` (RFC 9745), `Sunset` (RFC 8594, the date it stops working) and a
  `Link` to the changelog. These stay until that date, even after you acknowledge the
  notice; log or alert on `Sunset`.

Any key may call these, whatever its scopes. A change that needs you to act is announced at
least 30 days ahead in production (7 in the sandbox), except for a security fix.
[the changelog](/changelog) lists every release.

## 11. Your own obligations

- Your privacy notice covers sending documents and signer details to the service.
- Your retention rules cover your copies of documents and evidence.
- You are responsible for the content of documents and for having the right to send
  them.
- Your support channel answers signers' questions about your documents.
- If you learn a key has leaked, tell the operator immediately to revoke it.

## 12. Going live checklist

Complete in the **sandbox** first. The operator reviews it before issuing production
credentials.

- [ ] Keys are only on the server, loaded from a secret store, and never logged
- [ ] Every POST's idempotency key is saved before sending; recovery after a simulated
      timeout returns the original result with no duplicate
- [ ] A request that is still `preparing` is handled (409 then retry), not reported as a
      failure
- [ ] Signing links reach signers within their lifetime (Continue pattern or equivalent);
      the 6th link in an hour is handled
- [ ] Reissuing a link: the old one is refused and the new one signs
- [ ] Every issued link digest is recorded per signer
- [ ] Status arrives by verified, deduplicated webhooks or the event feed with a saved
      cursor
- [ ] Evidence is verified against pinned keys and your own records before the document
      is marked signed; a tampered bundle is refused
- [ ] Cancel and withdraw use a fresh `If-Match`
- [ ] All statuses in section 10 are handled; 429/503 back off
- [ ] Key rotation has been rehearsed
- [ ] Signers are told who is asking; privacy and retention notes are updated
- [ ] Notices reach a person: the `eDocInk-Notices` header or `checkCompatibility()` at
      startup is logged or alerted, and handled notices are acknowledged
