Introduction

Welcome to Essence Platform — a zero-knowledge personal data vault that puts privacy and security first.

What is Essence Platform?

Essence Platform is an API-first service that enables you to build applications where users truly own and control their personal data. All sensitive data is encrypted on the client side before it ever reaches our servers, ensuring true zero-knowledge architecture.

Key Features

🔐 Zero-Knowledge Encryption

• All data encrypted with AES-256-GCM on the client
• Server never has access to decryption keys
• Client-side key derivation with PBKDF2 (100,000+ iterations)

⚡ High Performance

• Average response time: <145ms
• Throughput: 1,200+ requests/second
• DataLoader optimization prevents N+1 queries

🎯 Developer Friendly

• Modern GraphQL API with real-time subscriptions
• Traditional REST API for compatibility
• TypeScript SDK with full type safety
• Interactive API playground

🌐 Multi-Instance Architecture

• Global instances for worldwide access
• Organization instances for enterprise
• Sovereign cloud for data residency compliance

🔑 Flexible Authentication

• JWT Bearer tokens
• API keys
• OAuth 2.0 support
• Fine-grained authorization policies

Core Concepts

Vaults

Vaults are containers for organizing encrypted data. Think of them as secure folders where users store their sensitive information.

const vault = await client.vaults.create({
  name: 'Medical Records',
  description: 'Personal health information',
  category: 'health'
});

Documents

Documents are individual pieces of encrypted data stored within vaults. They can be files, structured data, or any sensitive information.

const document = await client.documents.create({
  vaultId: vault.id,
  fileName: 'prescription.pdf',
  encryptedData: encryptedFile, // Already encrypted client-side
  metadata: {
    documentType: 'prescription',
    date: '2025-11-06'
  }
});

Instances

Instances represent different deployment environments. Users can route their data to specific geographic regions or organizational boundaries.

• Global Instance: Default, worldwide access
• Organization Instance: Enterprise deployments
• Sovereign Instance: Country-specific data residency

Users

Users are authenticated identities that own vaults and documents. Each user has:

• Unique identifier (UUID)
• Authentication credentials
• Associated instance
• API keys (optional)

How It Works

1. Client-Side Encryption

graph LR
    A[User Data] --> B[Client Encrypts<br/>AES-256-GCM]
    B --> C[Base64 Encode]
    C --> D[Send to API]
    D --> E[Store Encrypted Blob]

Your application encrypts data before sending it to our API:

import { encryptData } from '@essence-platform/sdk';

// Your plaintext data
const sensitiveData = {
  ssn: '123-45-6789',
  medicalHistory: '...'
};

// Encrypt client-side
const { encryptedData, encryptionMetadata } = await encryptData(
  JSON.stringify(sensitiveData),
  userEncryptionKey
);

// Send encrypted data to API
await client.documents.create({
  vaultId: vault.id,
  encryptedData,
  encryptionMetadata
});

2. Server Storage

The server:

• ✅ Receives encrypted blob (Base64)
• ✅ Validates format and authentication
• ✅ Stores encrypted data in PostgreSQL
• ❌ Never decrypts the data
• ❌ Never has the decryption keys

3. Client-Side Decryption

// Retrieve encrypted document
const document = await client.documents.get(documentId);

// Decrypt client-side
const decryptedData = await decryptData(
  document.encryptedData,
  userEncryptionKey,
  document.encryptionMetadata
);

const sensitiveData = JSON.parse(decryptedData);

Architecture Overview

┌─────────────────────────────────────────────────┐
│           Your Application                       │
│  ┌──────────────────────────────────────────┐  │
│  │   Essence SDK (TypeScript/JavaScript)    │  │
│  │  • Client-side encryption/decryption     │  │
│  │  • API client                            │  │
│  │  • Key management                        │  │
│  └──────────────────────────────────────────┘  │
└───────────────────┬─────────────────────────────┘
                    │ HTTPS
                    ▼
┌─────────────────────────────────────────────────┐
│           Essence Platform API                   │
│  ┌──────────────────────────────────────────┐  │
│  │   GraphQL / REST API                     │  │
│  │  • Authentication & Authorization        │  │
│  │  • Rate limiting                         │  │
│  │  • Encrypted blob storage                │  │
│  └──────────────────────────────────────────┘  │
└───────────────────┬─────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│           PostgreSQL Database                    │
│  • Stores encrypted blobs (bytea)               │
│  • No plaintext sensitive data                  │
│  • Metadata in plaintext (names, dates, etc)    │
└─────────────────────────────────────────────────┘

Use Cases

Healthcare Applications

Store patient medical records with true patient ownership:

// Patient creates their own health vault
const healthVault = await client.vaults.create({
  name: 'My Health Records',
  category: 'health'
});

// Upload encrypted medical record
const record = await uploadEncryptedDocument(
  healthVault.id,
  medicalPDF,
  patientEncryptionKey
);

// Share with doctor (time-limited)
const shareLink = await client.documents.share(record.id, {
  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
  permissions: ['read']
});

Financial Services

Secure KYC document storage:

const kycVault = await client.vaults.create({
  name: 'KYC Documents',
  category: 'financial'
});

await Promise.all([
  uploadEncryptedDocument(kycVault.id, passport, key),
  uploadEncryptedDocument(kycVault.id, proofOfAddress, key),
  uploadEncryptedDocument(kycVault.id, bankStatement, key)
]);

Enterprise Data Sovereignty

Deploy organization-specific instances:

// Route data to EU instance for GDPR compliance
const euClient = new EssenceClient({
  apiKey: apiKey,
  instanceId: 'eu-west-1-org-instance'
});

const vault = await euClient.vaults.create({
  name: 'EU Customer Data'
});

Security Guarantees

What Essence Platform Knows

✅ Metadata (non-sensitive):

• Vault names and descriptions
• Document filenames and sizes
• Upload timestamps
• User IDs and email addresses

What Essence Platform NEVER Knows

❌ Sensitive Data:

• Document contents
• Decryption keys
• Plaintext personal information
• Original file contents

Encryption Details

• Algorithm: AES-256-GCM (Authenticated Encryption)
• Key Derivation: PBKDF2-HMAC-SHA256
• Iterations: 100,000+ (configurable)
• IV: Randomly generated per document
• Auth Tag: Ensures data integrity

Compliance

Essence Platform helps you meet regulatory requirements:

• GDPR: User data ownership, right to be forgotten
• HIPAA: Encrypted PHI storage with audit logs
• SOC 2 Type II: Security controls (in progress)
• ISO 27001: Information security management (in progress)

API Overview

GraphQL API

Modern, flexible API with real-time capabilities:

query {
  vaults {
    id
    name
    documents {
      id
      fileName
      encryptedData
    }
  }
}

Features:

• 26 queries
• 9 mutations
• 4 real-time subscriptions
• Field-level authorization
• Query complexity limits

REST API

Traditional REST endpoints for compatibility:

GET /api/v1/vaults
POST /api/v1/vaults
GET /api/v1/vaults/{id}
DELETE /api/v1/vaults/{id}

Features:

• OpenAPI 3.0 specification
• Pagination support
• Filtering and sorting
• Standard HTTP status codes

Performance

Essence Platform is built for production scale:

Metric	Target	Actual
Average Response Time	<200ms	~145ms
95th Percentile	<300ms	~275ms
Throughput	1K req/sec	1.2K req/sec
Concurrent Requests	100	100+

Rate Limiting

Three tiers to match your needs:

Tier	Hourly Limit	GraphQL Limit	Burst
Free	1,000	100	10/min
Paid	10,000	5,000	100/min
Enterprise	100,000	50,000	1,000/min

Getting Started

Ready to build? Follow our Quick Start guide to make your first API call in 5 minutes.

Next Steps

1. Quick Start — Your first API call
2. Core Concepts — Understand the fundamentals
3. Authentication — Secure your application
4. Zero-Knowledge Encryption — Deep dive into encryption

---

Questions? Join our Discord community or email support.