Quick Start

Get started with Essence Platform API in 5 minutes! This guide will walk you through making your first API call.

Prerequisites

• Node.js 18+ or Python 3.9+
• A code editor
• 5 minutes of your time

Step 1: Create an Account (1 minute)

1. Visit app.essence.digital
2. Click Sign Up and create your account
3. Verify your email address

You'll receive a welcome email with:

• Account confirmation link
• Getting started resources
• Links to documentation

Step 2: Generate API Key (1 minute)

1. Sign in to your account at app.essence.digital
2. Navigate to Settings → API Keys
3. Click Generate New API Key
4. Give your key a descriptive name (e.g., "Development", "Production")
5. Select the appropriate scopes:
   • vaults:read - Read vault information
   • vaults:write - Create and update vaults
   • documents:read - Read documents
   • documents:write - Upload and manage documents
   • documents:share - Share documents with others
6. Click Create API Key
7. Copy your API key immediately (it won't be shown again)

API Key Format:

essence_sk_1234567890abcdefghijklmnopqrstuvwxyz

Important

• Store your API key securely in environment variables or a secrets manager
• Never commit it to source control or share it publicly
• Rotate keys regularly (every 90 days recommended)
• Use separate keys for development, staging, and production
• Revoke compromised keys immediately

Step 3: Install SDK (1 minute)

npm

npm install @essence-platform/sdk

pip

pip install essence-platform

Step 4: Make Your First API Call (2 minutes)

typescript

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

// Initialize the client
const client = new EssenceClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.essence.digital'
});

async function main() {
  // Get all vaults
  const vaults = await client.vaults.list();
  console.log('Your vaults:', vaults);

  // Create a new vault
  const newVault = await client.vaults.create({
    name: 'My First Vault',
    description: 'Created via API'
  });
  console.log('Created vault:', newVault.id);
}

main().catch(console.error);

javascript

const { EssenceClient } = require('@essence-platform/sdk');

// Initialize the client
const client = new EssenceClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.essence.digital'
});

async function main() {
  // Get all vaults
  const vaults = await client.vaults.list();
  console.log('Your vaults:', vaults);

  // Create a new vault
  const newVault = await client.vaults.create({
    name: 'My First Vault',
    description: 'Created via API'
  });
  console.log('Created vault:', newVault.id);
}

main().catch(console.error);

python

from essence_platform import EssenceClient

# Initialize the client
client = EssenceClient(
    api_key='your-api-key-here',
    base_url='https://api.essence.digital'
)

# Get all vaults
vaults = client.vaults.list()
print('Your vaults:', vaults)

# Create a new vault
new_vault = client.vaults.create(
    name='My First Vault',
    description='Created via API'
)
print('Created vault:', new_vault.id)

Step 5: Run Your Code

TypeScript

npx ts-node index.ts

JavaScript

node index.js

Python

python main.py

Expected Output

Your vaults: []
Created vault: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

✅ Success!

Congratulations! You've made your first API call to Essence Platform!

Understanding Authentication Flow

Let's understand what happened behind the scenes:

sequenceDiagram
    participant App as Your Application
    participant API as Essence API
    participant DB as Database

    App->>API: POST /api/v1/vaults<br/>Header: X-Api-Key: essence_sk_xxx
    API->>API: Validate API Key
    API->>API: Check Rate Limits
    API->>API: Verify Permissions (vaults:write)
    API->>DB: Create Vault Record
    DB-->>API: Vault Created
    API-->>App: 201 Created + Vault Data

Authentication Methods

Essence Platform supports three authentication methods:

1. API Key (Recommended for Server-to-Server)

# Using curl
curl -X GET https://api.essence.digital/api/v1/vaults \
  -H "X-Api-Key: essence_sk_your_key_here"

// Using SDK
const client = new EssenceClient({
  apiKey: process.env.ESSENCE_API_KEY
});

Best for:

• Backend services
• Server-to-server communication
• Automated processes
• CLI tools

2. JWT Bearer Token (Recommended for User Sessions)

# Using curl
curl -X GET https://api.essence.digital/api/v1/vaults \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

// Using SDK
const client = new EssenceClient({
  bearerToken: userJwtToken
});

Best for:

• Web applications
• Mobile apps
• User-specific actions
• OAuth 2.0 flows

3. OAuth 2.0 (Coming Soon)

Full OAuth 2.0 support for third-party integrations.

Learn more about authentication →

First API Call Examples

Example 1: Using cURL

# List all vaults
curl -X GET "https://api.essence.digital/api/v1/vaults" \
  -H "X-Api-Key: essence_sk_your_key_here" \
  -H "Content-Type: application/json"

# Create a vault
curl -X POST "https://api.essence.digital/api/v1/vaults" \
  -H "X-Api-Key: essence_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Vault",
    "description": "Created via cURL",
    "category": "personal"
  }'

# Get specific vault
curl -X GET "https://api.essence.digital/api/v1/vaults/{vault-id}" \
  -H "X-Api-Key: essence_sk_your_key_here"

Example 2: Using JavaScript/TypeScript

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

const client = new EssenceClient({
  apiKey: process.env.ESSENCE_API_KEY!,
  baseUrl: 'https://api.essence.digital'
});

async function demo() {
  try {
    // List all vaults
    const vaults = await client.vaults.list();
    console.log(`You have ${vaults.length} vaults`);

    // Create a new vault
    const vault = await client.vaults.create({
      name: 'My First Vault',
      description: 'Created via SDK',
      category: 'personal'
    });
    console.log('Created vault:', vault.id);

    // Get vault details
    const details = await client.vaults.get(vault.id);
    console.log('Vault name:', details.name);

    // Update vault
    const updated = await client.vaults.update(vault.id, {
      description: 'Updated description'
    });
    console.log('Updated:', updated.description);

  } catch (error) {
    console.error('Error:', error);
  }
}

demo();

Example 3: Using Python

from essence_platform import EssenceClient
import os

# Initialize client
client = EssenceClient(
    api_key=os.environ['ESSENCE_API_KEY'],
    base_url='https://api.essence.digital'
)

try:
    # List all vaults
    vaults = client.vaults.list()
    print(f'You have {len(vaults)} vaults')

    # Create a new vault
    vault = client.vaults.create(
        name='My First Vault',
        description='Created via Python SDK',
        category='personal'
    )
    print(f'Created vault: {vault.id}')

    # Get vault details
    details = client.vaults.get(vault.id)
    print(f'Vault name: {details.name}')

    # Update vault
    updated = client.vaults.update(
        vault.id,
        description='Updated description'
    )
    print(f'Updated: {updated.description}')

except Exception as error:
    print(f'Error: {error}')

Rate Limits

All API requests are subject to rate limiting to ensure platform stability:

Tier	Hourly Limit	GraphQL Complexity	Burst Rate	Cost
Free	1,000 requests	100 points	10/min	$0
Paid	10,000 requests	5,000 points	100/min	$29/mo
Enterprise	100,000 requests	50,000 points	1,000/min	Custom

Rate Limit Headers

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1699564800
X-RateLimit-Tier: free

Handling Rate Limits

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

async function makeRequest() {
  try {
    const vaults = await client.vaults.list();
    return vaults;
  } catch (error) {
    if (error instanceof RateLimitError) {
      // Rate limit exceeded
      console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);

      // Wait and retry
      await new Promise(resolve =>
        setTimeout(resolve, error.retryAfter * 1000)
      );

      return makeRequest(); // Retry
    }
    throw error;
  }
}

Learn more about rate limiting →

Error Handling Basics

The Essence Platform API returns structured errors with helpful information:

Error Response Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Vault not found",
    "details": {
      "vaultId": "vault-123"
    },
    "requestId": "req_1234567890",
    "timestamp": "2025-11-06T10:00:00Z"
  }
}

Common Error Codes

Code	HTTP Status	Description
INVALID_API_KEY	401	API key is invalid or missing
INSUFFICIENT_PERMISSIONS	403	API key lacks required scope
NOT_FOUND	404	Resource doesn't exist
VALIDATION_ERROR	400	Request validation failed
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error (contact support)

Error Handling Pattern

import {
  EssenceError,
  ValidationError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  RateLimitError
} from '@essence-platform/sdk';

async function robustVaultCreation(name: string) {
  try {
    const vault = await client.vaults.create({ name });
    console.log('✅ Success:', vault.id);
    return vault;

  } catch (error) {
    if (error instanceof ValidationError) {
      console.error('❌ Validation Error:', error.message);
      console.error('Invalid fields:', error.fields);
      // Handle validation errors (e.g., show to user)

    } else if (error instanceof AuthenticationError) {
      console.error('❌ Authentication Error:', error.message);
      // API key is invalid - check configuration

    } else if (error instanceof AuthorizationError) {
      console.error('❌ Authorization Error:', error.message);
      // API key lacks required scope - regenerate with correct scopes

    } else if (error instanceof NotFoundError) {
      console.error('❌ Not Found:', error.message);
      // Resource doesn't exist

    } else if (error instanceof RateLimitError) {
      console.error('❌ Rate Limited:', error.message);
      console.error(`Retry after: ${error.retryAfter}s`);
      // Implement exponential backoff

    } else if (error instanceof EssenceError) {
      console.error('❌ API Error:', error.code, error.message);
      // Other API errors

    } else {
      console.error('❌ Unexpected Error:', error);
      // Network errors, timeouts, etc.
    }

    throw error;
  }
}

Complete error code reference →

Testing Your Integration

1. Use the Development Environment

const client = new EssenceClient({
  apiKey: process.env.ESSENCE_DEV_API_KEY,
  baseUrl: 'https://dev-api.essence.digital' // Development environment
});

2. Try the Interactive Playground

Visit the GraphQL Playground to test queries interactively:

query GetVaults {
  vaults {
    id
    name
    documentCount
    createdAt
  }
}

3. Use Postman Collection

Import our Postman collection for easy testing:

Download Postman Collection →

What's Next?

Now that you've made your first API call, here are some next steps:

Learn the Basics

• Core Concepts — Understand vaults, documents, and instances
• Authentication — Learn about JWT tokens and API keys
• Zero-Knowledge Encryption — How client-side encryption works

Try Common Use Cases

• Creating Vaults — Organize your data
• Uploading Documents — Store encrypted files
• Sharing Documents — Secure document sharing

Explore the API

• GraphQL API — Modern API with real-time subscriptions
• REST API — Traditional REST endpoints
• GraphQL Playground — Try queries interactively

SDK Documentation

• Client Configuration — Advanced SDK setup
• Encryption — Client-side encryption
• Error Handling — Handle errors gracefully

Need Help?

• 📚 Browse Documentation
• 💬 Join Discord Community
• 📧 Email Support
• 🐛 Report Issues

Rate Limiting

Free tier includes:

• 1,000 requests/hour
• 100 GraphQL queries/hour
• 10 requests/minute burst limit

Need more? Check out our pricing plans.

Best Practices

Security First

• Never hardcode API keys in your code
• Use environment variables: process.env.ESSENCE_API_KEY
• Rotate API keys regularly
• Use separate keys for development and production

Error Handling

Always wrap API calls in try-catch blocks:

try {
  const vault = await client.vaults.create({ name: 'My Vault' });
} catch (error) {
  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    // Handle rate limiting
  }
  console.error('Error:', error.message);
}

---

Ready to build something amazing?
Check out our step-by-step tutorials →