Identity & encryption

Access user identity, device credentials, and end-to-end encryption for secure peer-to-peer communication.

webAI provides two APIs for identity and security: UserIdentityManager for accessing the current user’s identity, and E2ECrypto for encrypting and decrypting data between peers.

These APIs are especially useful when building collaborative apps where you need to identify participants or secure data in transit.

UserIdentityManager

UserIdentityManager provides access to the current user’s decentralized identity. In webAI, every device generates a unique identity called an ODID (On-Device Identity) — there are no accounts, no usernames, and no central identity server.

Getting the user’s identity

const getUserIdentityManager = () =>
  window.UserIdentityManager ?? window.parent?.UserIdentityManager ?? null;

async function getIdentity() {
  const im = getUserIdentityManager();
  if (!im) return { odid: 'local', displayName: 'You' };
  return im.getOrCreateIdentity();
}

getOrCreateIdentity()

Returns the current user’s device identity. If no identity exists yet, one is created automatically.

Returns: Promise<{ odid: string, displayName: string }>

Field	Type	Description
odid	string	The unique on-device identity string
displayName	string	The user’s chosen display name

getAuthHeaders()

Returns HTTP-style authentication headers for peer-to-peer requests. Useful when your app needs to make authenticated requests to other peers in a space.

async function getAuthHeaders() {
  const im = getUserIdentityManager();
  if (!im) return {};
  return im.getAuthHeaders();
}

Returns: Promise<object> — a headers object suitable for use with fetch() or similar.

Handling identity in local development

When running outside the webAI shell, UserIdentityManager is null. Return sensible defaults so your app still works:

async function getIdentity() {
  const im = getUserIdentityManager();
  if (!im) {
    return { odid: 'local-dev', displayName: 'You (dev mode)' };
  }
  return im.getOrCreateIdentity();
}

Using identity in your app

React

import { useState, useEffect } from 'react';

function UserBadge() {
  const [identity, setIdentity] = useState(null);

  useEffect(() => {
    getIdentity().then(setIdentity);
  }, []);

  if (!identity) return <span>Loading...</span>;

  return (
    <div className="user-badge">
      <strong>{identity.displayName}</strong>
      <code>{identity.odid.slice(0, 8)}...</code>
    </div>
  );
}

Vue

<template>
  <div class="user-badge" v-if="identity">
    <strong>{{ identity.displayName }}</strong>
    <code>{{ identity.odid.slice(0, 8) }}...</code>
  </div>
  <span v-else>Loading...</span>
</template>

<script setup>
import { ref, onMounted } from 'vue';

const identity = ref(null);
onMounted(async () => {
  identity.value = await getIdentity();
});
</script>

End-to-end encryption

The E2ECrypto API provides encrypt and decrypt helpers for securing data exchanged between peers. This is the same encryption layer used internally by the collaboration system.

const getE2ECrypto = () =>
  window.E2ECrypto ?? window.parent?.E2ECrypto ?? null;

encrypt(text, recipientPublicKeyJwk)

Encrypts plaintext using the recipient’s RSA public key.

• Algorithm: RSA-OAEP with SHA-256
• Input: plaintext string and recipient’s public key in JWK format
• Returns: Promise<string> — base64-encoded ciphertext

const crypto = getE2ECrypto();
const encrypted = await crypto.encrypt('Secret message', recipientPublicKey);

decrypt(encryptedBase64, privateKeyJwk)

Decrypts base64-encoded ciphertext using your private key.

• Algorithm: RSA-OAEP with SHA-256
• Input: base64 ciphertext string and your private key in JWK format
• Returns: Promise<string> — decrypted plaintext
• On failure, returns "[Unable to decrypt message]" instead of throwing

const crypto = getE2ECrypto();
const decrypted = await crypto.decrypt(encryptedPayload, myPrivateKey);

E2ECrypto is automatically used by the platform’s built-in collaboration features. You only need to use it directly if you’re building custom encrypted data flows on top of the collaboration layer.

API summary

API	Method	Description
UserIdentityManager	getOrCreateIdentity()	Returns the user’s ODID and display name
UserIdentityManager	getAuthHeaders()	Returns auth headers for P2P requests
E2ECrypto	encrypt(text, pubKeyJwk)	RSA-OAEP encrypt with recipient’s public key
E2ECrypto	decrypt(ciphertext, privKeyJwk)	RSA-OAEP decrypt with your private key

Next steps

App lifecycle

Build, bundle, and deploy your finished app.

Collaboration API

Combine identity with spaces for a full collaborative experience.