dApp SDK integration

The idOS Software Development Kit (SDK) has been developed to make it easier for dApps and other providers to interact with the idOS. Any web3 developer should be able to run the idOS SDK on their own by following the steps below and be able to ask users to share access to their idOS credentials and create new credentials for users, among others.

As of today, the idOS is only available in Ethereum and NEAR blockchains. If you are building in another ecosystem, please check the new ecosystem integration docs. Please also bear in mind the example below is for Ethereum dApps. For more information on how to integrate the SDK in other available ecosystems or further details, please check the detailed idOS SDK Documentation in GitHub.

1. Install the idOS SDK and initialize it

Create a container in your page and get our NPM package with pnpm add @idos-network/idos-sdk (or the equivalent of your package manager of choice).

import { idOS } from "@idos-network/idos-sdk";

// connect your user's wallet however you do it today, for example:
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send("eth_requestAccounts", []);
const signer = await provider.getSigner();

// initialize SDK
const idos = await idOS.init({ container: "#idos" });
await idos.auth.setEvmSigner(connectedSigner);
await idos.crypto.init();

2. Query the SDK

The SDK offers an interface to manage access grants and data, such as:

// see, get data/credentials from a connected user's idOS profile
idos.data.list()
idos.data.get()

// create, update, delete, validate data/credentials from a connected user's idOS profile
idos.data.create()
idos.data.update()
idos.data.delete()
idos.utils.validateCredential()

// see, create, revoke an access grant from the user
idos.grants.list()
idos.grants.create()
idos.grants.revoke()

By default, the idOS stores user data in the form of W3C Verifiable Credentials. To see, get, validate data from a connected user's idOS profile and their credentials you can use queries such as:

// example of credential-related queries
const { id } = credentials.find(c => c.credential_type === "basic");
const { content } = await idos.data.get("credentials", id);
const isValid = await idOS.verifiableCredentials.verify(content).catch(e => false)

Each identity verifier may use a different credential schema. A more comprehensive list of attributes from credentials issued by Fractal ID can be found here.

3. Redirect users without an existing idOS profile

To be able to query a user's idOS profile, they obviously need to have a profile first

if (humanId) { /* user has an idOS profile */ }

If your user doesn't have an idOS profile, you can send them to Fractal ID to get one, by redirecting them to the first URL in idos.ProfileProviders. By using that URL for user onboarding, you agree to the Fractal ID's Terms of Service. Please notice that this journey will only allow a user to get an idOS profile and receive a Proof-of-Personhood credential. If you need a dedicated user onboarding journey (e.g. KYC with a Proof of Address) please contact Fractal ID. More identity issuers will be listed in the near future once they integrate with the idOS.

if (!humanId) window.location = idOS.ProfileProviders [0];

If you have any additional questions on how to integrate the idOS SDK, please check the SDK detailed guide in GitHub. You can also see the README for a complete interface description and more usage examples, and try the idOS SDK dApp example to demo how the SDK could work with your dApp.