Docusign eSignature

1. Overview

The Docusign integration is a component of ys88.io's internal agreement automation stack. Internal users and agents use it to handle the signing leg of workflows that produce a legally binding document — engagement letters, consents, settlement agreements, internal approvals, and similar artifacts. Docusign performs signature capture, identity assurance, tamper-evident sealing, and audit certificate generation. ys88.io handles drafting, routing decisions, retries, archival, and the surrounding context that the workflow needs.

The integration is scoped to internal use by the account owner and authorized internal users. It is not resold, white-labeled, embedded in a consumer product, or exposed to external customers. Envelopes are sent only on behalf of the account owner or other authorized internal users, and only for the account owner's own agreements.

2. Primary capabilities

• Envelope creation — from a Docusign template or a raw document, with tab and recipient data computed at runtime.
• Recipient routing — determining signer order, CC lists, and role assignments based on the underlying case or matter.
• Status tracking — polling and Docusign Connect webhook events so downstream steps (notifications, filing, ledger updates) run as soon as signing completes.
• Document download — retrieving completed envelopes, the audit (Certificate of Completion), and attachments for archival.
• Template management — listing and reading templates so workflows can select the correct one for a given flow.
• Voiding and resend — cancelling stale envelopes and nudging slow signers, respecting Docusign's cadence limits and API policy.

3. Endpoints used

The integration calls the following Docusign eSignature REST API v2.1 endpoints. No other Docusign product APIs (CLM, Monitor, Rooms, etc.) are used.

• GET /accounts/{accountId} — account metadata and base URI resolution
• POST /accounts/{accountId}/envelopes — envelope creation (from template or document)
• GET /accounts/{accountId}/envelopes — listing envelopes by status and date range
• GET /accounts/{accountId}/envelopes/{envelopeId} — envelope status retrieval
• GET /accounts/{accountId}/envelopes/{envelopeId}/recipients — recipient status
• GET /accounts/{accountId}/envelopes/{envelopeId}/documents — document listing
• GET /accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId} — document download
• PUT /accounts/{accountId}/envelopes/{envelopeId} — void or resend operations
• GET /accounts/{accountId}/templates and GET /accounts/{accountId}/templates/{templateId} — template read

4. Authentication & consent

ys88.io authenticates to Docusign using the OAuth 2.0 JWT Grant flow, per the Docusign Authentication documentation:

1. An RSA keypair is generated for the integration key inside the Docusign developer account. The private key is stored as an encrypted secret in ys88.io's secret store.
2. The account owner grants admin consent to the integration through the standard Docusign OAuth consent URL, authorizing the signature and impersonation scopes. These are the minimum scopes required to create and manage envelopes on behalf of the account owner.
3. At runtime, ys88.io generates a JWT assertion signed with the private key, exchanges it for a short-lived access token against Docusign's identity endpoint, and caches the token in memory for its advertised lifetime.
4. If a token is rejected, ys88.io re-requests; if the rejection indicates consent has been revoked, the integration halts and alerts the account owner rather than retrying blindly.

Consent can be revoked at any time through the Docusign Admin → Connected Apps panel. Doing so immediately disables the integration.

5. Data handling

• In transit: All calls to Docusign use TLS 1.2 or higher. Connect webhook deliveries are verified by HMAC signature using the shared secret configured in Docusign Admin.
• At rest: Cached envelope metadata and downloaded documents are stored in encrypted object storage. Access tokens, refresh material, and the RSA private key are stored in a separate encrypted secret store.
• Minimization: The integration requests only the fields and documents it needs. Signer PII is handled only to the extent necessary to complete signing and archival.
• Retention: Completed envelopes and audit certificates are retained per the surrounding matter's retention policy. Working copies cached inside ys88.io are pruned on a rolling basis once archival completes.
• Logging & audit: Every Docusign call is logged with request id, envelope id (where applicable), status, and latency, for audit, debugging, and cost attribution. Logs are retained for a bounded window and are not shared with third parties.
• No training use: Signer content is not used to train any machine-learning model.

6. Security

• Least-privilege scopes (signature, impersonation only).
• All secrets encrypted at rest; access scoped to the specific workload that needs them.
• Webhook signature verification is mandatory; unsigned or invalid deliveries are rejected and logged.
• Idempotency: envelope creation uses client-generated idempotency keys to prevent duplicate envelopes on retry.
• Incident response: suspected compromise of the integration key, private key, or webhook secret triggers immediate rotation and a review of audit logs. Any incident affecting signer data will be notified to the account owner without undue delay.

7. Error handling

• Retryable failures (5xx, timeouts, 429 rate limits) are retried with exponential backoff and jitter, honoring Docusign's Retry-After header.
• Non-retryable failures (4xx other than 429) surface to the workflow, which either corrects the input and retries or escalates for human review.
• Connect webhook deliveries are deduplicated by envelope id plus event timestamp, and verified by HMAC signature before processing.
• Stuck envelopes are surfaced via scheduled status checks; the account owner is alerted rather than silently voiding.

8. Compliance

• Signatures collected via Docusign rely on Docusign's compliance with the U.S. ESIGN Act and UETA, and, where relevant, the EU eIDAS regulation. ys88.io does not attempt to replicate or override those guarantees.
• The integration does not bypass Docusign's signing UX; all signers interact with Docusign directly through Docusign-hosted signing pages or Docusign-native notifications.
• The integration complies with the Docusign API Terms of Use and API Use Policies, including the prohibitions on reselling access, misrepresenting the Docusign brand, and storing signer credentials.

9. Scope & restrictions

• Used for internal agreement workflows owned by the account holder.
• Envelopes are not sent on behalf of unrelated third parties, and the integration is not resold, white-labeled, or exposed to external customers.
• No signer credentials or Docusign account passwords are ever captured or stored.
• The integration does not attempt to modify Docusign's signing UX, inject content into Docusign-hosted pages, or bypass identity checks.

10. Support & contact

For questions about this integration — including security, data handling, or to request a capability change — email [email protected]. For issues specific to the Docusign service itself, refer to Docusign Support.

11. References

• Docusign eSignature REST API documentation
• Docusign OAuth 2.0 JWT Grant authentication
• Docusign Trust Center
• Docusign API Terms of Use
• Docusign Privacy Policy
• ys88.io Privacy Policy
• ys88.io Terms & Conditions