# Getting Started

> Get started with Korala's document signing API in minutes

Source: https://docs.korala.ai/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**: Signs your requests. Keep it out of client-side code.

### 2. Install the API Client

    ```bash
    npm install @korala/api-client
    ```
    cURL works without installation. Sign each request with HMAC as shown below.

### 3. Send Your First Document

    ```typescript
    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: 'john@example.com',
      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);
    ```
    ```bash
    # Set your credentials
    API_KEY="your-api-key-id"
    API_SECRET="your-api-secret"
    BASE_URL="https://api.korala.ai"

    # Generate timestamp and signature
    TIMESTAMP=$(date +%s)
    METHOD="POST"
    PATH="/api/v1/documents/upload-url"
    BODY='{"filename":"contract.pdf","contentType":"application/pdf"}'

    SIGNATURE=$(echo -n "${TIMESTAMP}.${METHOD}.${PATH}.${BODY}" | \
      openssl dgst -sha256 -hmac "${API_SECRET}" | cut -d' ' -f2)

    # Create upload URL
    curl -X POST "${BASE_URL}${PATH}" \
      -H "Content-Type: application/json" \
      -H "X-API-Key: ${API_KEY}" \
      -H "X-Timestamp: ${TIMESTAMP}" \
      -H "X-Signature: ${SIGNATURE}" \
      -d "${BODY}"
    ```

## 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:

| Header | Description |
|--------|-------------|
| `X-API-Key` | Your API key ID |
| `X-Timestamp` | Current Unix timestamp (seconds) |
| `X-Signature` | HMAC-SHA256 signature |

The signature is computed as:
```
HMAC-SHA256(secret, "{timestamp}.{METHOD}.{path}.{body}")
```

See the [Authentication Guide](https://docs.korala.ai/docs/guides/authentication) 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](https://docs.korala.ai/docs/guides/webhooks) for setup instructions.

## Next Steps

- [Example App](https://github.com/korala-ai/doc-signing-example) - Full Next.js example with single-signer, multi-signer, and batch countersign demos
- [Authentication Guide](https://docs.korala.ai/docs/guides/authentication) - HMAC authentication in detail
- [Documents Guide](https://docs.korala.ai/docs/guides/documents) - Document management
- [API Reference](https://docs.korala.ai/api-reference) - Complete API documentation