Identity & encryption

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 (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 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
Vue

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>
  );
}

<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

Getting Started

Platform APIs

Building & Deploying

UserIdentityManager

Getting the user’s identity

`getOrCreateIdentity()`

`getAuthHeaders()`

Handling identity in local development

Using identity in your app

End-to-end encryption

`encrypt(text, recipientPublicKeyJwk)`

`decrypt(encryptedBase64, privateKeyJwk)`

API summary

Next steps

App lifecycle

Collaboration API

Getting Started

Platform APIs

Building & Deploying

​UserIdentityManager

​Getting the user’s identity

​getOrCreateIdentity()

​getAuthHeaders()

​Handling identity in local development

​Using identity in your app

​End-to-end encryption

​encrypt(text, recipientPublicKeyJwk)

​decrypt(encryptedBase64, privateKeyJwk)

​API summary

​Next steps

App lifecycle

Collaboration API

UserIdentityManager

Getting the user’s identity

`getOrCreateIdentity()`

`getAuthHeaders()`

Handling identity in local development

Using identity in your app

End-to-end encryption

`encrypt(text, recipientPublicKeyJwk)`

`decrypt(encryptedBase64, privateKeyJwk)`

API summary

Next steps