Quickstart

00 Prerequisites

Before you begin, make sure you have:

• Node.js 18+ or Deno 1.30+ installed
• npm or yarn package manager
• Basic familiarity with async/await JavaScript

01 Understanding Entity-to-Entity

Before diving into code, it's important to understand how Private.Me differs from traditional API-based integrations. This conceptual foundation will help you see why identity-based connections eliminate entire classes of operational problems.

The API Key Problem

Traditional M2M authentication relies on bearer tokens—API keys, OAuth credentials, JWT tokens. These create three fundamental problems:

• Leakage: API keys end up in logs, git commits, Slack messages, and environment variables with overly broad access. Once exposed, attackers have the same access as legitimate services.
• Rotation complexity: Rotating keys means updating every service that holds the key—a manual, error-prone process requiring coordination across teams.
• Cascading failures: When a token expires mid-workflow, the entire process restarts from zero. A 4-hour ETL pipeline failing at hour 3 means tripled compute cost, missed SLA, and manual intervention at 2am.

Entity-to-Entity: The Paradigm Shift

Private.Me replaces the asymmetric client-server model with entity-to-entity connections. Instead of "client with API key" → "server with identity," both sides have cryptographic identities and verify each other.

// Traditional API: asymmetric trust
fetch('https://api.example.com/endpoint', {
  headers: { 'Authorization': 'Bearer sk_live_...' }  // ← API key leaks
});

// Private.Me: bilateral cryptographic identity
const agent = await Agent.quickstart();
await agent.connect(targetDid);              // ← Both sides verify
await agent.send({ type: "ping" });          // ← No secrets transmitted

Why This Matters: Cascading Failure Elimination

When tokens can't expire (because there are no tokens), cascading failures can't happen. Consider this real-world scenario:

Fast Onboarding

Traditional API key setup: 42-67 minutes (account creation, key generation, secret management, SDK installation, configuration, testing). Private.Me: < 2 minutes with zero-config service discovery and automatic trust establishment.

Bilateral Authentication

Both parties prove their identity via Ed25519 signatures. The server verifies the client, and the client verifies the server. This prevents server impersonation attacks and eliminates the need for TLS certificate pinning.

Now that you understand why entity-to-entity matters, let's build your first identity-based connection.

02 Installation

Install the Private.Me agent SDK via npm. The SDK provides identity-based authentication using Ed25519/X25519 cryptographic identities (DIDs).

npm install @private.me/agent-sdk

The SDK includes everything you need: identity generation, trust registry management, secure communication, and XorIDA threshold sharing.

03 Create Your Identity

Every ACI (Authenticated Confidential Interface) is identified by a DID (Decentralized Identifier). Generate your identity in one line:

import { generateIdentity } from '@private.me/agent-sdk';

const identity = await generateIdentity();
console.log('Your DID:', identity.did);

// Output: did:key:z6Mkr...

Your identity consists of an Ed25519 signing keypair and an X25519 encryption keypair, both derived from the same seed. The DID is cryptographically bound to your public keys—there's no central registry or certificate authority.

Store Your Identity Securely

The identity includes private keys. Store them securely using OS keychain or encrypted storage:

import { storeIdentity } from '@private.me/agent-sdk';

// Stores in OS keychain (macOS/Windows) or encrypted file (Linux)
await storeIdentity(identity, { name: 'my-service' });

04 Send Your First Message

Connect to an ACI and send an authenticated message. No API keys required—authentication is cryptographic:

import { connect } from '@private.me/agent-sdk';

// Connect to a service ACI
const conn = await connect('payments');

// Send authenticated message
const result = await conn.value.agent.send({
  to: 'did:key:z6Mkv...',  // recipient DID
  payload: { amount: 100, currency: 'USD' }
});

if (result.ok) {
  console.log('Message sent:', result.value);
}

Expected Response

{
  ok: true,
  value: {
    messageId: "msg_7x9k2...",
    timestamp: 1714089600000,
    status: "delivered"
  }
}

The message is automatically encrypted using XorIDA threshold sharing. The recipient reconstructs it using their identity. No shared secrets, no key exchange ceremony.

What Happened Under the Hood

• Mutual Authentication: Both parties prove their identity via Ed25519 signatures
• Ephemeral Keys: X25519 ECDH generates session keys that never touch the network
• Threshold Sharing: XorIDA splits the payload into shares (2-of-2 by default)
• Replay Prevention: Each message includes a unique nonce and timestamp
• HMAC Integrity: HMAC-SHA256 verification before reconstruction

05 Trust Registry Basics

ACIs use a trust registry to map service names to DIDs. This replaces DNS-based service discovery with cryptographic identity:

import { MemoryTrustRegistry } from '@private.me/trust';

const registry = new MemoryTrustRegistry();

// Register a service DID
await registry.register({
  name: 'payments',
  did: 'did:key:z6Mkv...',
  publicKey: '...',
  metadata: { tier: 'production' }
});

// Resolve service by name
const service = await registry.resolve('payments');
console.log('Service DID:', service.value.did);

In production, use FileTrustRegistry for persistent storage or NetworkTrustRegistry for distributed environments. The registry is pluggable—bring your own storage backend.

06 Next Steps

You've successfully created an identity, sent an authenticated message, and configured a trust registry. Here's where to go next:

Explore Core ACIs

• xLink — Machine-to-machine identity and cascading failure elimination
• xChange — Secure message exchange with XorIDA threshold sharing
• xPass — Password-free authentication using cryptographic identities
• xStore — Threshold-split encrypted storage

Learn the Concepts

• ACIs vs APIs — Understand identity-based interfaces
• Security Model — Information-theoretic security guarantees
• Platform Architecture — How the 205 ACIs fit together

Production Deployment

• Full Control — Self-hosted deployment guide
• AWS Compatible — Deploy ACIs alongside AWS services
• M2M / IoT Use Cases — Real-world identity-based architectures