Skip to Content
GuidesAudit Trail

Audit Trail

Every Korala document maintains a complete audit trail that records each action from creation through completion. The audit trail is immutable — events can never be modified or deleted.

Event Types

EventDescription
document_createdDocument was uploaded and created
document_sentDocument was sent for signing
document_viewedA signer opened the document
field_filledA signer filled in a field value
signature_appliedA signature image was applied to a field
document_signedA signer completed all their fields
document_completedAll signers finished — document is cryptographically sealed
document_failedDocument completion failed after retries
document_voidedDocument was cancelled before completion
document_declinedA signer declined to sign
reminder_sentA signing reminder was sent to a signer
access_revokedA signer’s access was revoked

Retrieving the Audit Trail

import { KoralaClient } from '@korala/api-client';
 
const korala = new KoralaClient({
  apiKeyId: 'your-api-key-id',
  apiSecret: 'your-api-secret',
});
 
const events = await korala.documents.getAuditTrail(documentId);
 
for (const event of events) {
  console.log(`${event.createdAt} — ${event.eventType}`);
  if (event.ipAddress) {
    console.log(`  IP: ${event.ipAddress}`);
  }
  if (event.signerId) {
    console.log(`  Signer: ${event.signerId}`);
  }
}

Event Details

Each audit event includes:

FieldTypeDescription
idstringUnique event identifier
documentIdstringThe document this event belongs to
signerIdstring | nullThe signer who triggered the event (if applicable)
eventTypestringOne of the event types listed above
ipAddressstring | nullIP address of the actor
claimedIpAddressstring | nullPartner-asserted end-user IP (from X-Client-IP header)
userAgentstring | nullBrowser or client user agent
metadataobject | nullAdditional context (e.g., field ID for field_filled)
createdAtstringISO 8601 timestamp

Response Format

[
  {
    "id": "evt_abc123",
    "documentId": "doc_xyz789",
    "signerId": null,
    "eventType": "document_created",
    "ipAddress": "203.0.113.1",
    "claimedIpAddress": null,
    "userAgent": "KoralaClient/1.0",
    "metadata": null,
    "createdAt": "2024-01-14T09:00:00Z"
  },
  {
    "id": "evt_def456",
    "documentId": "doc_xyz789",
    "signerId": "sgn_abc123",
    "eventType": "document_signed",
    "ipAddress": "198.51.100.42",
    "claimedIpAddress": "192.0.2.10",
    "userAgent": "Mozilla/5.0...",
    "metadata": { "bulkSign": false },
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

Certificate of Completion

When a document is completed, Korala automatically generates a Certificate of Completion PDF that summarizes the entire audit trail. This certificate includes:

  • Document name and ID
  • All signers with their signing timestamps
  • IP addresses and user agents for each action
  • Cryptographic signature verification details

The certificate is available as certificateFileUrl on the completed document:

const document = await korala.documents.get(documentId);
 
if (document.status === 'completed' && document.certificateFileUrl) {
  // Download the Certificate of Completion
  const certificate = await fetch(document.certificateFileUrl);
  fs.writeFileSync('certificate.pdf', await certificate.buffer());
}

IP Address Tracking

Korala captures two IP address fields per event:

  • ipAddress — The IP address observed by Korala’s servers (the direct connection)
  • claimedIpAddress — The end-user’s IP address asserted by your application via the X-Client-IP request header

If you’re using the API on behalf of end users (e.g., through a backend proxy), pass the X-Client-IP header so the audit trail reflects the actual user’s IP rather than your server’s.

Using Audit Trails for Compliance

Audit trails are essential for legal compliance in electronic signatures. They provide evidence of:

  • Intent to sign — The signer viewed the document and actively filled fields
  • Identity — IP address, user agent, and timing establish who signed
  • Integrity — The cryptographic seal and RFC 3161 timestamp prove the document hasn’t been modified since signing
  • Non-repudiation — The complete event history makes it difficult for a signer to deny their participation
Last updated on
TemplatesWebhooks