idOS Client JavaScript SDK

⚖️ Legalities

By downloading, installing, or implementing any of the idOS’ SDKs, you acknowledge that you have read and understood idOS’ Privacy Policy and Transparency Document.

• https://www.idos.network/legal/privacy-policy
• https://www.idos.network/legal/transparency-document

Installation

Get our NPM package and its dependencies with pnpm or the equivalent of your package manager of choice:

pnpm add @idos-network/client

Quick start

import {
  createIDOSClient,
  idOSClientLoggedIn,
  type idOSClientWithUserSigner,
} from "@idos-network/client";

const idOSClientWithoutSigner = await createIDOSClient({
  nodeUrl: "https://nodes.idos.network",
  enclaveOptions: {
    container: "#idosContainer",
  },
}).createClient();

// Signer can be JsonRpcSigner, or check below for supported chains
const idOSClientWithSigner = await idOSClientWithoutSigner.withUserSigner(signer);

// Check if user is already in idOS onboarded
const hasProfile = await idOSClientWithSigner.hasProfile();

// If yes we can create a new session
const loggedInClient = await idOSClientWithSigner.logIn();

// User id and public encryption key
const profile = loggedInClient.user;

// Now we can filer over users credentials (no access to them)
const credentials = await loggedInClient.filterCredentials({
  credentialLevelOrHigherFilter: {
    userLevel: "basic",
    requiredAddons: ["email", "liveness"],
  },
});

// If we found a credentials which we can use, we will ask user for AccessGrant
// which we later can use in our consumer to get the users data
const ag = await loggedInClient.requestAccessGrant(credentials[0].id, {
  consumerAuthPublicKey: "CONSUMER_PUBLIC_KEY",
  consumerEncryptionPublicKey: "CONSUMER_ENC_PUBLIC_KEY",
  lockedUntil: lockedUntil: Math.floor(Date.now() / 1000) + 90 * 24 * 60 * 60, // 3 months from now
});

// Also when the user is logged in, we can ask him to add another wallet
// wallet type is required.
await loggedInClient.addWallet({
  id: "unique-wallet-id",
  address: "0x...", // Wallet address
  public_key: "0x...", // Public key in hex format
  message: "Sign this message to prove you own this wallet",
  signature: "0x...", // Signature of the message
  wallet_type: "EVM", // Required: "EVM", "NEAR", "XRPL"...
});

Supported Wallet Types

• "evm" - Ethereum Virtual Machine compatible wallets (Ethereum, Polygon, etc.)
• "xrpl" - XRP Ledger wallets
• "near" - NEAR Protocol wallets
• "stellar" - Stellar network wallets

Documentation

For complete documentation, examples, and implementation guides:

• 📖 Client Guide - Comprehensive implementation guide
• 🏗️ System Overview - Understanding idOS architecture
• 🔒 Encryption - Encryption key management
• ✍️ Signatures - Signer implementation details

Key Features

• Profile & Session Lifecycle - Check profile existence, attach a wallet signer, and log users in/out
• Enclave-Backed Encryption - Generate user encryption profiles and decrypt credential content safely via the enclave
• Credential Access & Filtering - Fetch credentials, read decrypted content, and filter by issuer, level, and field rules
• Credential Sharing Flows - Request DAG/DWG messages, create access grants, and share credentials with controlled lock times
• Wallet Management - Add, list, and remove wallets (single or batch), including MPC-aware wallet synchronization
• Multi-Chain Wallet Support - Works with EVM, NEAR, XRPL, and Stellar wallet types

Support

Please follow the process outlined here: https://github.com/idos-network/.github/blob/main/profile/README.md

Developing the SDK locally

Run:

pnpm dev

This will start the compiler in watch mode that will rebuild every time any of the source files are changed.

You can also create a production build by running the following command in the root folder of the SDK package:

pnpm build