Implement security best practices for Documenso document signing integrations.
Use when securing API keys, configuring webhooks securely,
or implementing document security measures.
Trigger with phrases like "documenso security", "secure documenso",
"documenso API key security", "documenso webhook security".
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"),
Buffer.from(expected, "utf8")
);
}
# Python equivalent
import hmac, os
from flask import request
def verify_webhook(req):
received = req.headers.get("X-Documenso-Secret", "")
expected = os.environ["DOCUMENSO_WEBHOOK_SECRET"]
return hmac.compare_digest(received, expected)
Step 4: Document Access Control
// Principle of least privilege with API keys
// Personal keys: only YOUR documents
// Team keys: all documents in the team
// Restrict document access by checking ownership
async function getDocumentSecure(documentId: number, userId: string) {
const doc = await client.documents.getV0(documentId);
// Verify the requesting user is the owner or a recipient
const isOwner = doc.userId === parseInt(userId);
const isRecipient = doc.recipients?.some(r => r.email === userEmail);
if (!isOwner && !isRecipient) {
throw new Error("Access denied: not authorized for this document");
}
return doc;
}
