Get Started

Your first encrypted message

Goal

Encrypt a message addressed to your own identity, send the resulting envelope through any transport, and decrypt it on the receiving side. This walkthrough uses a single identity for both ends to keep setup simple. The same pattern works between any two identities.

Prerequisites

• The SDK installed (Installation)
• An activated identity (Activating an identity)

Step 1 — Create the client

// .NET
using HexaEight.Bridge;

var client = new Client();
Console.WriteLine($"I am: {client.Name}");

// Node.js
import { HexaEight } from '@hexaeight/sdk';

const he = await HexaEight.connect();
console.log(`I am: ${he.name}`);

Step 2 — Encrypt a message

Call EncryptEnvelopeAsync with the recipient's identity name and the body to send. The return value is the wire envelope, a text string you can store or transmit.

// .NET
string envelope = await client.EncryptEnvelopeAsync(
    recipient: client.Name,         // self for this walkthrough
    body:      "hello from agent");

// Node.js
const envelope = await he.envelope.encrypt({
    recipient: he.name,
    body:      'hello from agent',
});

Step 3 — Decrypt the envelope

The decrypt call returns an object containing the verified sender name, the body, and an authorisation status.

// .NET
var msg = await client.DecryptEnvelopeAsync(envelope);
Console.WriteLine($"Sender:     {msg.Sender}");
Console.WriteLine($"Body:       {msg.Body}");
Console.WriteLine($"Authorized: {msg.Authorized}");

// Node.js
const msg = await he.envelope.decrypt(envelope);
console.log(`Sender:     ${msg.sender}`);
console.log(`Body:       ${msg.body}`);
console.log(`Authorized: ${msg.authorized}`);

Step 4 — Verify the output

I am: web0-bliss-cyan-radar84
Sender:     web0-bliss-cyan-radar84
Body:       hello from agent
Authorized: Allowed

The Sender field is the cryptographically verified identity of whoever produced the envelope. Because the SDK successfully decrypted the envelope, this name is trustworthy — only someone with the matching HexaEight credentials could have produced it.

Sending to a different identity

To send to a different identity, change the recipient argument to their identity name. The receiving side runs the same decrypt code but must have the recipient identity activated locally so the SDK can fetch the correct decryption key.

// .NET — sending to [email protected]
string envelope = await client.EncryptEnvelopeAsync(
    recipient: "[email protected]",
    body:      "hello alice");

Sending the envelope over a network

The wire envelope is just a string. You can put it in:

• The body of an HTTP POST
• A message on a queue (Kafka, RabbitMQ, SQS, Service Bus)
• A file in shared storage
• A notification service like ntfy

The SDK does not care how you transport it. Choose whatever is appropriate for your application's reliability and latency needs.