Documenso Debug Bundle

Output

• A minimal redacted diagnostic bundle with correlation IDs, lifecycle state, environment, version, and status evidence.
• A safe escalation/recovery record that preserves document/signature confidentiality and audit integrity.

Examples

For a signing failure, collect opaque document/correlation IDs, template version, environment, state transition, callback result, and timestamp. Review the bundle for document content, signer PII, signing links, tokens, and audit payloads before sharing; reproduce only with synthetic documents through the approved incident/support route.

Current State

!node --version 2>/dev/null || echo 'N/A' !python3 --version 2>/dev/null || echo 'N/A' !uname -a

Overview

Comprehensive debugging tools for Documenso integration issues. Includes diagnostic scripts, curl debug commands, environment verification, and support ticket templates.

Prerequisites

• Documenso SDK installed
• Access to logs and configuration
• curl and jq available

Instructions

Step 1: Quick Connectivity Test

#!/bin/bash
set -euo pipefail

echo "=== Documenso Connectivity Test ==="

# 1. Check API key is set
if [ -z "${DOCUMENSO_API_KEY:-}" ]; then
  echo "FAIL: DOCUMENSO_API_KEY not set"
  exit 1
fi
echo "OK: API key set (${#DOCUMENSO_API_KEY} chars)"

# 2. Test authentication
BASE="${DOCUMENSO_BASE_URL:-https://app.documenso.com/api/v1}"
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=1")

if [ "$STATUS" = "200" ]; then
  echo "OK: API authentication successful"
elif [ "$STATUS" = "401" ]; then
  echo "FAIL: Invalid API key (401)"
  exit 1
elif [ "$STATUS" = "403" ]; then
  echo "FAIL: Insufficient permissions (403) — try a team API key"
  exit 1
else
  echo "WARN: Unexpected status $STATUS"
fi

# 3. Check latency
LATENCY=$(curl -s -o /dev/null -w "%{time_total}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=1")
echo "Latency: ${LATENCY}s"

# 4. List recent documents
echo "=== Recent Documents ==="
curl -s -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=5" | jq '.documents[] | {id, title, status, createdAt}'

Step 2: TypeScript Diagnostic Script

// scripts/documenso-diagnose.ts
import { Documenso } from "@documenso/sdk-typescript";

async function diagnose() {
  const results: Arr

Documenso Deploy Integration

Output

• A versioned, staged document/signing deployment with owner approval, validation evidence, and rollback reference.
• A protected promotion path that prevents unreviewed configurations from affecting production documents or signers.

Examples

Deploy a synthetic document workflow to staging with scoped credentials, verify authorization, signing lifecycle, webhook verification, and redacted alerts, then use an approved production canary. Stop and roll back if audience, access, or lifecycle behavior differs; do not place document data or signing links in deployment logs.

Overview

Deploy Documenso-integrated applications and self-hosted Documenso instances to Docker, Kubernetes, serverless, and cloud platforms. Covers both app deployment (your code that uses the Documenso API) and self-hosted Documenso deployment.

Prerequisites

• Application ready for deployment
• Cloud platform account (AWS, GCP, Azure)
• Docker installed locally
• Completed documenso-multi-env-setup

Instructions

Step 1: Dockerize Your Documenso Integration

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runtime
WORKDIR /app
RUN addgroup -S app && adduser -S app -G app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json .
USER app
EXPOSE 3000
CMD ["node", "dist/server.js"]
# Note: DOCUMENSO_API_KEY injected at runtime, never baked into image

Step 2: Self-Hosted Documenso (Docker Compose)

# docker-compose.prod.yml
services:
  documenso:
    image: documenso/documenso:latest
    ports:
      - "3000:3000"
    environment:
      - NEXTAUTH_URL=https://sign.yourcompany.com
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}   # openssl rand -hex 32
      - NEXT_PRIVATE_ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=${ENCRYPTION_SECONDARY_KEY}
      - NEXT_PUBLIC_WEBAPP_URL=https://sign.yourcompany.com
      - NEXT_PRIVATE_DATABASE_URL=postgresql://documenso:${DB_PASS}@db:5432/documenso
      - NEXT_PRIVATE_DIRECT_DATABASE_URL=postgresql://documenso:${DB_PASS}@db:5432/documenso
      # SMTP
      - NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
      - NEXT_PRIVATE_SMTP_HOST=${SMTP_HOST}
      - NEXT_PRIVATE_SMTP_PORT=587
      - NEXT_PRIVATE_SMTP_USERNAME=${SMTP_USER}
      - NEXT_PRIVATE_SMTP_PASSWORD=${SMTP_PASS}
      - NEXT_PRIVATE_SMTP_FROM_ADDRESS=signing@yourcompany.com
      - NEXT_PRIVATE_SMTP_FROM_NAME=YourCompany Signing
      # Signing certificate
      - NEXT_PRIVATE_SIGNING_PASSPHRASE=${CERT_PASSPHRASE}
    volumes:
      - ./certs/signing-cert.p12:/opt/documenso/cert.p12:ro
    depend

Documenso Enterprise RBAC

Output

• A least-privilege role/project configuration with named owners, access-review evidence, and a tested revocation path.
• Verified separation between development/staging/production document and signer permissions.

Examples

Grant a development service account only the document action and project it needs, validate it with a synthetic document, and confirm it cannot view or sign production documents. Record the owner and review date; revoke overly broad access and correct group mapping before proceeding.

Overview

Configure team-based access control and enterprise features in Documenso. The Team plan enables multi-user collaboration with shared documents. Enterprise adds SSO (OIDC), audit logging, and organization-level management.

Prerequisites

• Documenso Team or Enterprise plan
• Understanding of RBAC concepts
• For SSO: OIDC-compatible identity provider (Okta, Azure AD, Google Workspace, Auth0)

Documenso Team Model

Organization
├── Team A
│   ├── Owner (full control)
│   ├── Admin (manage members, settings)
│   └── Member (create, view, sign team documents)
├── Team B
│   └── ...
└── Personal Accounts (separate from teams)

Key concepts:

• Teams are separate from personal accounts -- team documents are owned by the team
• Team API keys access all team documents; personal keys only access personal documents
• Each team member can have Owner, Admin, or Member role
• Unlimited teams and users on Team/Enterprise plans (early adopter pricing)

Instructions

Step 1: Team API Key Scoping

import { Documenso } from "@documenso/sdk-typescript";

// Personal key: only YOUR documents
const personalClient = new Documenso({
  apiKey: process.env.DOCUMENSO_PERSONAL_KEY!,
});

// Team key: all documents in the team
const teamClient = new Documenso({
  apiKey: process.env.DOCUMENSO_TEAM_KEY!,
});

// Common mistake: using personal key for team operations
// Results in 403 Forbidden on team resources

Step 2: Application-Level RBAC

Documenso handles team membership internally. For finer-grained control in your app, implement an authorization layer:

// src/auth/documenso-rbac.ts
type Role = "viewer" | "editor" | "admin" | "owner";

interface TeamMember {
  userId: string;
  teamId: string;
  role: Role;
}

const PERMISSIONS: Record<Role, string[]> = {
  viewer: ["documents:read"],
  editor: ["documents:read", "documents:create", "documents:send"],
  admin: ["documents:read", "documents:create", "documents:send", "documents:delete", "members:manage"],
  owner: ["

Documenso Hello World

Output

• A verified synthetic development document/signing workflow with a redacted lifecycle receipt.
• A cleanup/disable action that leaves no real signer or production-document tutorial artifact.

Examples

Create a development document using placeholder content and a synthetic signer, verify the intended role and lifecycle transition, then archive/delete it under the test policy. Record only environment and opaque correlation/state; never use a real agreement, signer, signing URL, or production workspace for a hello-world exercise.

Overview

Minimal working example that creates a document, adds a recipient with a signature field, and sends it for signing — all in one script. Uses the Documenso TypeScript SDK (v2 API) with a Python equivalent.

Prerequisites

• Completed documenso-install-auth setup
• Valid API key in DOCUMENSO_API_KEY environment variable
• A PDF file to upload (or generate a test one below)

Instructions

Step 1: Generate a Test PDF (Optional)

If you don't have a PDF handy:

npm install pdf-lib

// generate-test-pdf.ts
import { PDFDocument, StandardFonts } from "pdf-lib";
import { writeFileSync } from "fs";

async function createTestPdf() {
  const pdf = PDFDocument.create();
  const page = (await pdf).addPage([612, 792]); // US Letter
  const font = await (await pdf).embedFont(StandardFonts.Helvetica);
  page.drawText("Please sign below:", { x: 50, y: 700, size: 16, font });
  const bytes = await (await pdf).save();
  writeFileSync("test-contract.pdf", bytes);
  console.log("Created test-contract.pdf");
}
createTestPdf();

Step 2: Complete Signing Workflow (TypeScript)

// documenso-hello.ts
import { Documenso } from "@documenso/sdk-typescript";
import { readFileSync } from "fs";

async function main() {
  const client = new Documenso({
    apiKey: process.env.DOCUMENSO_API_KEY!,
  });

  // 1. Create a document
  const doc = await client.documents.createV0({
    title: "Hello World Contract",
  });
  console.log(`Document created: ID ${doc.documentId}`);

  // 2. Upload the PDF
  const pdfBuffer = readFileSync("test-contract.pdf");
  await client.documents.setFileV0(doc.documentId, {
    file: new Blob([pdfBuffer], { type: "application/pdf" }),
  });

  // 3. Add a recipient (signer)
  const recipient = await client.documentsRecipients.createV0(doc.documentId, {
    email: "signer@example.com",
    name: "Jane Doe",
    role: "SIGNER",
  });
  console.log(`Recipient added: ${recipient.recipientId}`);

  // 4. Add a signature field at specific coordinates
  await client.documentsField

Documenso Incident Runbook

Instructions

1. Declare the incident scope, commander, affected documents/signers/environment, and safe communication channel.
2. Stabilize with the approved pause, access-revocation, or rollback action before deep diagnosis.
3. Collect only redacted correlation/state/audit evidence; preserve document/signature integrity and chain of custody.
4. Verify recovery, notify owners, and create follow-up work for root cause and prevention.

Output

• A time-stamped incident record with scope, owner, mitigation, redacted evidence, and verified recovery or escalation.

Examples

For unauthorized document access, restrict affected credentials or sharing immediately, capture opaque document/correlation IDs and redacted audit state, and verify access is restored only to the intended role. Escalate according to policy; do not share documents, signing links, or signer PII in incident chat.

Overview

Step-by-step procedures for responding to Documenso integration incidents. Covers cloud outages, self-hosted issues, and integration failures.

Prerequisites

• Access to monitoring dashboards
• Documenso dashboard access
• Application log access
• On-call escalation contacts defined

Severity Levels

Quick Diagnostic Commands

#!/bin/bash
set -euo pipefail
echo "=== Documenso Incident Diagnostic ==="

# 1. Check Documenso cloud status
echo "--- Cloud Status ---"
curl -s https://status.documenso.com/api/v2/status.json 2>/dev/null | jq '.status' || echo "Status page unreachable"

# 2. Check our API connectivity
echo "--- API Connectivity ---"
BASE="${DOCUMENSO_BASE_URL:-https://app.documenso.com/api/v1}"
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $DOCUMENSO_API_KEY" \
  "$BASE/documents?page=1&perPage=1" 2>/dev/null || echo "000")
echo "API Status: $HTTP_CODE"

# 3. Check latency (5 samples)
echo "--- Latency Check ---"
for i in $(seq 1 5); do
  LATENCY=$(curl -s -o /dev/null -w "%{time_total}" \
    -H "Authorization: Bearer $DOC

Documenso Install & Auth

Output

• A scoped Documenso credential/reference for the intended environment, with a verified low-impact authorization check.
• A secret-ownership and revocation path that keeps tokens and signing material out of repositories and logs.

Examples

Inject a development credential from the approved secret manager, create or read a synthetic document through a least-privilege role, and record only environment/result. If a key or signing URL is exposed, revoke it first and reissue after investigation; do not reuse it while attempting cleanup.

Overview

Set up the Documenso SDK and configure API authentication for document signing. Covers the TypeScript SDK (@documenso/sdk-typescript), the Python SDK (documenso-sdk-python), and raw REST API usage. Documenso exposes two API versions: v1 (legacy, documents only) and v2 (envelopes, multi-document, recommended for new work).

Prerequisites

• Node.js 18+ or Python 3.10+
• Package manager (npm, pnpm, yarn, pip, or uv)
• Documenso account — cloud at app.documenso.com or self-hosted instance
• API key generated from the Documenso dashboard

Instructions

Step 1: Install the SDK

TypeScript / Node.js:

npm install @documenso/sdk-typescript
# or
pnpm add @documenso/sdk-typescript

Python:

pip install documenso-sdk-python
# or
uv pip install documenso-sdk-python

Step 2: Generate an API Key

1. Log in to your Documenso dashboard (https://app.documenso.com or your self-hosted URL).
2. Click your avatar (top-right) and select User settings (or Team settings for team-scoped keys).
3. Navigate to the API tokens tab.
4. Click Create API Key, give it a descriptive name (e.g. ci-pipeline-prod).
5. Copy the key immediately — it is shown only once.

Team API keys inherit the team's document and template access. Personal keys only access your own documents.

Step 3: Store the Key Securely

# .env (never commit this file)
DOCUMENSO_API_KEY=api_xxxxxxxxxxxxxxxxxxxxxxxxxx

Add .env to .gitignore:

echo ".env" >> .gitignore

Step 4: Initialize the Client

TypeScript — v2 API (recommended):

import { Documenso } from "@documenso/sdk-typescript";

const documenso = new Documenso({
  apiKey: process.env.DOCUMENSO_API_KEY!,
  // For self-hosted, override the server URL:
  // serverURL: "https://sign.your

Documenso Local Dev Loop

Output

• A small test-backed local change using synthetic documents/signers and a normal source-control rollback path.
• A redacted development verification receipt without document content, signing links, credentials, or signer PII.

Examples

Use a development workspace with a synthetic template and signer, make one integration/config change, run its focused tests and a bounded lifecycle check, then inspect redacted status. Commit only reviewed changes; never use production documents, signing URLs, or credentials in local development.

Overview

Configure a fast local development environment for Documenso integrations. Covers project structure, environment configs, self-hosted Documenso via Docker, test utilities, and cleanup scripts.

Prerequisites

• Completed documenso-install-auth setup
• Node.js 18+ with TypeScript
• Docker (for self-hosted local Documenso)

Instructions

Step 1: Project Structure

my-signing-app/
├── src/
│   └── documenso/
│       ├── client.ts          # Configured SDK client
│       ├── documents.ts       # Document operations
│       ├── recipients.ts      # Recipient management
│       └── webhooks.ts        # Webhook handlers
├── scripts/
│   ├── verify-connection.ts   # Quick health check
│   ├── create-test-doc.ts     # Generate test documents
│   └── cleanup-test-docs.ts   # Remove test data
├── tests/
│   └── integration/
│       ├── document.test.ts
│       └── template.test.ts
├── .env.development
├── .env.test
└── .env.production

Step 2: Environment Configuration

.env.development:

DOCUMENSO_API_KEY=api_dev_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_dev_xxxxxxxxxxxx
LOG_LEVEL=debug

.env.test:

DOCUMENSO_API_KEY=api_test_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxx
LOG_LEVEL=warn

Step 3: Client Wrapper with Dev Helpers

// src/documenso/client.ts
import { Documenso } from "@documenso/sdk-typescript";

let _client: Documenso | null = null;

export function getClient(): Documenso {
  if (!_client) {
    _client = new Documenso({
      apiKey: process.env.DOCUMENSO_API_KEY!,
      ...(process.env.DOCUMENSO_BASE_URL && {
        serverURL: process.env.DOCUMENSO_BASE_URL,
      }),
    });
  }
  return _client;
}

// Dev helper: list recent documents for debugging
export async function listRecentDocs(limit = 5) {
  const client = getClient();
  const { documents } = await client.documents.findV0({
    page: 1,
    perPage: limit,
    orderByColumn: "createdAt",
    orderByDirection: "desc&

Documenso Migration Deep Dive

Output

• A staged migration record with document/template/signing compatibility evidence, owner, observation window, and rollback path.
• Preserved prior documents/configuration until the migration acceptance and retention requirements are complete.

Examples

Migrate a synthetic document/template set in development, verify roles, state transitions, callbacks, audit evidence, and retention, then promote through staging before a production canary. Stop and roll back on authorization, signing, or audit regression; never bulk-migrate sensitive documents as a test.

Current State

!npm list 2>/dev/null | head -10

Overview

Comprehensive guide for migrating to Documenso from other e-signature platforms (DocuSign, HelloSign, PandaDoc, Adobe Sign). Uses the Strangler Fig pattern for zero-downtime migration with feature flags and rollback support.

Prerequisites

• Current signing platform documented (APIs, templates, webhooks)
• Documenso account configured (see documenso-install-auth)
• Feature flag infrastructure (LaunchDarkly, environment variables, etc.)
• Parallel run capability (both platforms active during migration)

Migration Strategy: Strangler Fig Pattern

Phase 1: Parallel Systems (Week 1-2)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│ Old Platform │  (100% traffic)
│          │     └─────────────┘
│          │────▶│  Documenso   │  (shadow: log only, don't send)
└──────────┘     └─────────────┘

Phase 2: Gradual Cutover (Week 3-4)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│ Old Platform │  (50% traffic via feature flag)
│          │     └─────────────┘
│          │────▶│  Documenso   │  (50% traffic)
└──────────┘     └─────────────┘

Phase 3: Full Migration (Week 5+)
┌──────────┐     ┌─────────────┐
│ Your App │────▶│  Documenso   │  (100% traffic)
└──────────┘     └─────────────┘
                 Old platform decommissioned

Instructions

Step 1: Pre-Migration Assessment

// scripts/assess-current-system.ts
// Inventory your current signing platform usage

interface MigrationAssessment {
  platform: string;
  activeTemplates: number;
  documentsPerMonth: number;
  webhookEndpoints: string[];
  recipientRoles: string[];
  fieldTypes: string[];
  integrations: string[];  // CRM, database, etc.
}

async function assessCurrentSystem(): Promise<MigrationAssessment> {
  // Example for DocuSign
  return {
    platform: "DocuSign",
    activeTemplates: 15,
    documentsPerMonth: 200,
    webhookEndpoints: [
      "https://api.yourapp.com/webhooks/docusign",
    ],
    recipientRoles: ["Signer", "CC", "In Person Signer"],
    fieldTypes: ["Signature", "Date", "Text", "Che

Documenso Multi-Environment Setup

Output

• Isolated development, staging, and production workspaces with separate scoped identities, templates, signer controls, and audit boundaries.
• A promotion/rollback receipt based on synthetic validation rather than production document or signer experiments.

Examples

Validate a versioned template and callback in development using synthetic recipients, promote to staging with separate credentials, and record its lifecycle/authorization/alert results. Release production through an approved canary only; if any gate differs, restore the prior configuration and do not copy production keys or signing artifacts into lower environments.

Overview

Configure Documenso across development, staging, and production with environment isolation, secret management, and promotion workflows. Documenso cloud offers a staging environment at stg-app.documenso.com; self-hosted users run separate instances.

Prerequisites

• Documenso accounts or instances for each environment
• Secret management solution (Vault, AWS Secrets Manager, or .env files)
• Completed documenso-install-auth setup

Environment Architecture

┌─────────────────────────────────────────────────────────────┐
│  Development                                                 │
│  API: stg-app.documenso.com (or localhost:3000 self-hosted) │
│  Key: DOCUMENSO_API_KEY=api_dev_xxx                         │
│  Webhooks: ngrok tunnel                                      │
├─────────────────────────────────────────────────────────────┤
│  Staging                                                     │
│  API: stg-app.documenso.com                                 │
│  Key: DOCUMENSO_API_KEY=api_stg_xxx                         │
│  Webhooks: staging.yourapp.com/webhooks/documenso           │
├─────────────────────────────────────────────────────────────┤
│  Production                                                  │
│  API: app.documenso.com (or sign.yourcompany.com)           │
│  Key: DOCUMENSO_API_KEY=api_prod_xxx                        │
│  Webhooks: api.yourapp.com/webhooks/documenso               │
└─────────────────────────────────────────────────────────────┘

Instructions

Step 1: Environment Configuration Files

# .env.development
DOCUMENSO_API_KEY=api_dev_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_dev_xxxxxxxxxxxx
LOG_LEVEL=debug
NODE_ENV=development

# .env.staging
DOCUMENSO_API_KEY=api_stg_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_stg_xxxxxxxxxxxx
LOG_LEVEL=info
NODE_ENV=staging

# .env.production
DOCUMENSO_API_KEY=api_prod_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_prod_xx

Documenso Observability

Output

• Redacted, bounded metrics/traces for document lifecycle, signing state, errors, latency, and rate headroom.
• An owned alert/runbook path that protects signer identity, document content, and credentials.

Examples

Emit aggregate counts by environment, document state, and status class while excluding document bodies, signer email, signing URLs, IP addresses, tokens, and audit payloads. Trigger a development signing-state alert with a synthetic document, verify the on-call route, then retain only the redacted receipt.

Overview

Implement monitoring, structured logging, and health checks for Documenso integrations. Since Documenso does not expose rate limit headers or usage metrics via API, observability is built around your API call patterns, latency, error rates, and webhook delivery.

Prerequisites

• Working Documenso integration
• Monitoring stack (Prometheus/Grafana, Datadog, or CloudWatch)
• Logging infrastructure

Instructions

Step 1: Instrumented Client Wrapper

// src/observability/documenso-metrics.ts
import { Documenso } from "@documenso/sdk-typescript";

interface Metrics {
  requestCount: number;
  errorCount: number;
  totalLatencyMs: number;
  errorsByStatus: Record<number, number>;
}

const metrics: Metrics = {
  requestCount: 0,
  errorCount: 0,
  totalLatencyMs: 0,
  errorsByStatus: {},
};

export function createInstrumentedClient(): Documenso {
  const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

  return new Proxy(client, {
    get(target, prop) {
      const value = (target as any)[prop];
      if (typeof value === "object" && value !== null) {
        return new Proxy(value, {
          get(innerTarget, method) {
            const fn = (innerTarget as any)[method];
            if (typeof fn !== "function") return fn;

            return async (...args: any[]) => {
              const start = Date.now();
              metrics.requestCount++;

              try {
                const result = await fn.apply(innerTarget, args);
                metrics.totalLatencyMs += Date.now() - start;
                return result;
              } catch (err: any) {
                metrics.errorCount++;
                const status = err.statusCode ?? 0;
                metrics.errorsByStatus[status] = (metrics.errorsByStatus[status] || 0) + 1;
                metrics.totalLatencyMs += Date.now() - start;
                throw err;
              }
            };
          },
        });
      }
      return value;
    },
  });
}

// Expose metrics for Prometheus scraping
export function getMetrics() {
  return {
    ...metrics,
    avgLatencyMs: metrics.requestCount > 0
      ? Math.round(metrics.totalLatencyMs / metrics.requestCount)
      : 0,
    errorRate: metrics.requestC

Documenso Performance Tuning

Output

• A measured performance change with document/signing lifecycle, authorization, audit, and reliability guardrails.
• A reversible change record with aggregate metrics, owner, threshold, and rollback decision.

Examples

Measure synthetic-document workflow latency, throughput, error rate, and callback completion in staging, change one approved capacity/cache/concurrency setting, and compare against baseline. Revert if signing state, authorization, audit, or error behavior regresses; do not use real documents or weaken controls to improve a benchmark.

Overview

Optimize Documenso integrations for speed and efficiency. Key strategies: reduce API round-trips with templates, cache document metadata, batch operations with concurrency control, and use async processing for bulk signing workflows.

Prerequisites

• Working Documenso integration
• Redis or in-memory cache (recommended)
• Completed documenso-sdk-patterns setup

Instructions

Step 1: Reduce API Calls with Templates

The biggest performance win: templates reduce a multi-step document creation (create + upload + add recipients + add fields + send = 5+ calls) to just 2 calls (create from template + send).

// WITHOUT templates: 5+ API calls per document
async function createDocumentManual(signer: { email: string; name: string }) {
  const doc = await client.documents.createV0({ title: "Contract" });              // 1
  await client.documents.setFileV0(doc.documentId, { file: pdfBlob });             // 2
  const recip = await client.documentsRecipients.createV0(doc.documentId, {        // 3
    email: signer.email, name: signer.name, role: "SIGNER",
  });
  await client.documentsFields.createV0(doc.documentId, {                          // 4
    recipientId: recip.recipientId, type: "SIGNATURE",
    pageNumber: 1, pageX: 10, pageY: 80, pageWidth: 30, pageHeight: 5,
  });
  await client.documents.sendV0(doc.documentId);                                   // 5
}

// WITH templates: 2 API calls per document
async function createDocumentFromTemplate(templateId: number, signer: { email: string; name: string }) {
  const res = await fetch(                                                          // 1
    `${BASE}/templates/${templateId}/create-document`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        title: `Contract — ${signer.name}`,
        recipients: [{ email: signer.email, name: signer.name, role: "SIGNER" }],
      }),
    }
  );
  const doc = await res.json();
  await fetch(`${BASE}/documents/${doc.documentId}/send`, {                         // 2
    method: "POST",
    headers: { Authorization: 

Documenso Production Checklist

Instructions

1. Complete evidence gates for workspace/identity, template/version review, signer authorization, data/retention, callbacks, audit, monitoring, and rollback.
2. Validate the exact production role/audience and signing lifecycle with approved safe checks.
3. Stop production enablement when any document, identity, security, or owner gate is unverified.
4. Record the named go/no-go decision and post-release observation result.

Output

• A production-readiness receipt with owners, evidence links, approved exceptions, and tested rollback path.

Examples

Validate a new template in staging with synthetic signers, verify the production access roles and callback endpoint under review, then release to an approved canary. If authorization, state, or audit behavior differs, halt the release and restore the prior approved template.

Overview

Complete checklist for deploying Documenso integrations to production, covering security, reliability, monitoring, and compliance readiness.

Prerequisites

• Staging environment tested and verified
• Production API keys available
• Deployment pipeline configured (see documenso-ci-integration)
• Monitoring ready (see documenso-observability)

Production Checklist

1. Authentication & Secrets

• [ ] Production API key generated (not staging key)
• [ ] API key stored in secret manager (Vault, AWS Secrets Manager, not .env)
• [ ] Webhook secret configured and verified
• [ ] Key rotation procedure documented
• [ ] Old/unused keys revoked
• [ ] Self-hosted: secrets generated with openssl rand -hex 32
• [ ] Self-hosted: signing certificate from trusted CA mounted

2. Error Handling

• [ ] All API calls wrapped in try/catch with typed errors
• [ ] Exponential backoff for 429/5xx responses
• [ ] Circuit breaker for Documenso outages
• [ ] User-friendly error messages (no raw API errors exposed)
• [ ] Error tracking integration (Sentry, Datadog, etc.)

3. Performance

• [ ] Singleton client pattern (not creating new client per request)
• [ ] Templates used for repetitive document creation
• [ ] Bulk operations use concurrency control (p-queue)
• [ ] Background processing for non-critical operations (Bull/BullMQ)
• [ ] Document metadata cached (completed documents immutable)

4. Monitoring & Alerting

• [ ] Health check endpoint: GET /health/documenso
• [ ] API error rate alerting (> 5% for 5 minutes)
• [ ] Latency monitoring (p95 > 5s)
• [ ] Webhook delivery success rate tracking
• [ ] Structured logging with sanitized PII

5.

Documenso Reference Architecture

Instructions

1. Map document producers, templates, recipients, signing actions, audit records, webhooks, and retention boundaries to named owners.
2. Enforce least-privilege identity and separate development/staging/production workspaces and credentials.
3. Define idempotent lifecycle transitions, signed callbacks, redacted observability, and a rollback/incident path before production exposure.
4. Review architecture changes through normal security, data, and change-control processes.

Output

• A documented document/signing architecture with trust boundaries, ownership, and reversible integration points.

Examples

Route a synthetic development document through a scoped service identity, role-limited signer, validated webhook, and redacted audit metric. Promote the same versioned workflow through staging before a production canary; preserve a disabled/rollback path and do not include document URLs or signer identity in diagrams or logs.

Overview

Production-ready architecture for Documenso document signing integrations. Covers project layout, layered service architecture, webhook processing, and data flow.

Prerequisites

• Understanding of layered architecture principles
• Documenso SDK knowledge (see documenso-sdk-patterns)
• TypeScript project with Node.js 18+

Recommended Project Structure

my-signing-app/
├── src/
│   ├── documenso/
│   │   ├── client.ts              # Singleton SDK client
│   │   ├── errors.ts              # Custom error classes
│   │   ├── retry.ts               # Retry/backoff logic
│   │   └── types.ts               # Shared types
│   ├── services/
│   │   ├── document-service.ts    # Document CRUD operations
│   │   ├── template-service.ts    # Template-based workflows
│   │   └── signing-service.ts     # Orchestrates signing flows
│   ├── webhooks/
│   │   ├── handler.ts             # Express webhook router
│   │   ├── verify.ts              # Secret verification
│   │   └── processors/
│   │       ├── document-completed.ts
│   │       ├── document-signed.ts
│   │       └── document-rejected.ts
│   ├── api/
│   │   ├── health.ts              # Health check endpoint
│   │   └── routes.ts              # API routes
│   └── config/
│       └── index.ts               # Environment configuration
├── scripts/
│   ├── verify-connection.ts       # Quick health check
│   ├── create-test-doc.ts         # Test document generator
│   └── cleanup-test-docs.ts       # Test data cleanup
├── tests/
│   ├── unit/
│   │   └── document-service.test.ts
│   ├── integration/
│   │   └── document-lifecycle.test.ts
│   └── mocks/
│       └── documenso.ts           # Mock client factory
├── .env.development
├── .env.production
├── docker-compose.yml             # Self-hosted Documenso (dev)
└── package.json

Layer Archi

Documenso Security Basics

Output

• A least-privilege Documenso configuration with scoped secrets, signer/document access controls, and an incident/revocation path.
• A tested boundary for document authorization, webhook validation, and safe audit logging.

Examples

Create a development document with a synthetic signer, validate that only its intended role can view or act on it, and verify any webhook signature before processing. If a token, signing URL, or document is exposed, revoke/contain access and follow the incident procedure before attempting cleanup.

Overview

Essential security practices for Documenso integrations: API key management, webhook verification, document access control, and self-hosted signing certificate configuration.

Prerequisites

• Documenso account with API access
• Understanding of environment variables and secret management
• Completed documenso-install-auth setup

Instructions

Step 1: API Key Security

// NEVER hardcode keys
const BAD = new Documenso({ apiKey: "api_abc123..." }); // Exposed in source

// ALWAYS use environment variables
const GOOD = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

Key management rules:

• Store in .env (never committed) or a secrets manager (Vault, AWS Secrets Manager)
• Use team-scoped keys for team resources, personal keys for personal documents
• Rotate keys on employee offboarding -- revoke in dashboard immediately
• CI/CD: use masked/encrypted secrets (GitHub Secrets, GitLab CI variables)

# .gitignore — always include
.env
.env.*
!.env.example

Step 2: Key Rotation with Zero Downtime

// Support dual keys during rotation
function getApiKey(): string {
  // Try primary first, fall back to secondary during rotation
  return process.env.DOCUMENSO_API_KEY_PRIMARY
    ?? process.env.DOCUMENSO_API_KEY_SECONDARY
    ?? (() => { throw new Error("No Documenso API key configured"); })();
}

// Rotation procedure:
// 1. Generate new key in Documenso dashboard
// 2. Set as DOCUMENSO_API_KEY_SECONDARY, deploy
// 3. Verify secondary key works
// 4. Move secondary to PRIMARY, deploy
// 5. Revoke old key in dashboard

Step 3: Webhook Secret Verification

import { timingSafeEqual } from "crypto";

function verifyWebhookSecret(req: Request): boolean {
  const received = req.headers["x-documenso-secret"] as string;
  const expected = process.env.DOCUMENSO_WEBHOOK_SECRET!;

  if (!received || !expected) return false;

  // Use constant-time comparison to prevent timing attacks
  return timingSafeEqual(
    Buffer.from(received, "utf8"),
 

Documenso Upgrade & Migration

Output

• A versioned upgrade record with compatibility, access/audit checks, staged evidence, and a verified rollback revision.
• A paused/reversible release decision when any signing, authorization, or retention requirement regresses.

Examples

Upgrade in a development workspace using synthetic documents and signers, test the previous and target versions for lifecycle, callback, access, and audit behavior, then stage a canary. Retain the prior release/configuration and roll back immediately if a control fails; do not validate upgrades by changing live signed documents.

Current State

!npm list @documenso/sdk-typescript 2>/dev/null || echo 'SDK not installed' !npm list documenso-sdk-python 2>/dev/null || pip show documenso-sdk-python 2>/dev/null | head -3 || echo 'Python SDK not installed'

Overview

Guide for upgrading between Documenso API versions and SDK updates. Documenso has two API versions: v1 (legacy, document-centric) and v2 (recommended, envelope-based with multi-document support). The TypeScript and Python SDKs use the v2 API by default.

Prerequisites

• Current Documenso integration working
• Test environment available
• Feature flag system (recommended for gradual rollout)

API Version Comparison

Instructions

Step 1: Upgrade SDK to Latest

# Check current version
npm list @documenso/sdk-typescript

# Upgrade
npm install @documenso/sdk-typescript@latest

# Check for breaking changes
npm info @documenso/sdk-typescript changelog

# Python
pip install --upgrade documenso-sdk-python

Step 2: v1 REST to v2 SDK Migration

// BEFORE: v1 REST API
const BASE = "https://app.documenso.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` };

// Create document
const res = await fetch(`${BASE}/documents`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSO

Documenso Webhooks & Events

Output

• A verified signed, idempotent webhook/event path with redacted observability and recovery ownership.
• A receipt that records correlation ID, environment, event type, lifecycle result, and safe retry decision.

Examples

Validate the callback signature before parsing the event, deduplicate with an opaque event ID, acknowledge within the documented timeout, and log only state/result metadata. Test in development using a synthetic document; retry transient errors with bounded backoff and quarantine terminal failures without replaying signing actions blindly.

Overview

Configure and handle Documenso webhooks for real-time document lifecycle notifications. Webhooks require a Teams plan or higher. The webhook secret is sent via the X-Documenso-Secret header (not HMAC-signed -- it is a shared secret comparison).

Prerequisites

• Documenso team account (webhooks require teams)
• HTTPS endpoint for webhook reception
• Completed documenso-install-auth setup

Supported Events

Instructions

Step 1: Create Webhook via Dashboard

1. Log into Documenso, navigate to Team Settings > Webhooks.
2. Click Create Webhook.
3. Enter your HTTPS endpoint URL.
4. Select the events you want to receive.
5. (Optional) Enter a webhook secret -- this value will be sent as-is in the X-Documenso-Secret header on every request.
6. Save.

Step 2: Webhook Handler (Express)

// src/webhooks/documenso.ts
import express from "express";

const router = express.Router();
const WEBHOOK_SECRET = process.env.DOCUMENSO_WEBHOOK_SECRET!;

// Middleware: verify the shared secret
function verifySecret(req: express.Request, res: express.Response, next: express.NextFunction) {
  const secret = req.headers["x-documenso-secret&