Skip to Content
Getting Started

Getting Started

Korala is a document signing API that provides cryptographic PDF signing with RFC 3161 timestamping for legally compliant digital signatures.

Quick Start

1. Get Your API Credentials

First, create an API key from your Korala admin dashboard. You’ll receive:

  • API Key ID: A public identifier for your key
  • API Secret: A secret used to sign requests (keep this secure!)

2. Install the API Client

npm install @korala/api-client

3. Send Your First Document

import { KoralaClient } from '@korala/api-client';
 
const korala = new KoralaClient({
  apiKeyId: 'your-api-key-id',
  apiSecret: 'your-api-secret',
});
 
// Create a document and get upload URL
const { documentId, uploadUrl } = await korala.documents.createUploadUrl({
  filename: 'contract.pdf',
  contentType: 'application/pdf',
});
 
// Upload your PDF
await fetch(uploadUrl, {
  method: 'PUT',
  body: pdfBuffer,
  headers: { 'Content-Type': 'application/pdf' },
});
 
// Confirm the upload
await korala.documents.confirmUpload(documentId);
 
// Add a signer
const signer = await korala.signers.create(documentId, {
  email: '[email protected]',
  name: 'John Doe',
});
 
// Add a signature field
await korala.fields.create(documentId, {
  signerId: signer.id,
  fieldType: 'signature',
  pageNumber: 1,
  xPosition: 100,
  yPosition: 500,
  width: 200,
  height: 50,
});
 
// Send for signing
await korala.documents.send(documentId);

Core Concepts

Document Lifecycle

  1. Draft - Document is created but not yet sent
  2. Pending - Document has been sent and is awaiting signatures
  3. Completed - All signers have signed; document is cryptographically sealed
  4. Voided - Document was cancelled before completion
  5. Expired - Document expired before all signatures were collected

Authentication

Korala uses HMAC-SHA256 signature authentication for API requests. Each request must include:

HeaderDescription
X-API-KeyYour API key ID
X-TimestampCurrent Unix timestamp (seconds)
X-SignatureHMAC-SHA256 signature

The signature is computed as:

HMAC-SHA256(secret, "{timestamp}.{METHOD}.{path}.{body}")

See the Authentication Guide for details.

Webhooks

Korala sends webhook notifications for document events:

  • document_created - Document was created
  • document_sent - Document was sent for signing
  • document_viewed - A signer viewed the document
  • document_signed - A signer completed signing
  • document_completed - All signatures collected, document sealed
  • document_voided - Document was voided
  • document_declined - A signer declined to sign

See the Webhooks Guide for setup instructions.

Next Steps

Last updated on
Authentication