The primary features provided by the Issuer SDK are:
checking if your user has an idOS profile, and create one otherwise;
transforming IDV results into idOS credentials;
implementing a Passporting-compliant onboarding flow.
Getting started: what you'll need
Compliance guidance
See for more context, and discuss with your compliance officer:
whether you’re going to be using Passporting.
Signature and encryption keys
🛑 DANGER 🛑
Make sure you don't lose access to either secret keys. Otherwise, you won't be able to authenticate or decrypt credential contents. The idOS team won't be able to help you.
You'll need:
encryptionSecretKey: base64-encoded nacl.BoxKeyPair secret key. It'll be used to encrypt the credentials you issue to your users
see Encryption for more information
signingKeyPair: this can be a NEAR KeyPair, a nacl.SignKeyPair, or an ethers.Wallet. This will be used to sign RPC calls to the idOS nodes.
see Signatures for more information
You'll also need a multibaseSigningKeyPair, which will be used to sign the W3C VCs you issue. If you're unfamiliar with how to generate one, you can use the following example:
If they don't have a profile, you must create one for them. This procedure can only be done by a Permissioned Issuer. Get in touch with us at engineering@idos.network if you're interested in being one.
To create a user profile in idOS, you need:
A wallet address associated with the user.
A public encryption key derived from either a password chosen by the user in the idOS enclave app.
Step 1: Deciding on a user id
// backend
const userId = crypto.randomUUID();
// Remember it on your database
// e.g. session.user.update({ userId });
// Return it to the front-end to be used in the next step
return { userId }
Step 2: Getting the user's signing and encryption public keys
Use the idOSClient.discoverUserEncryptionPublicKey function to derive a public key for the user. This key will be used to encrypt and decrypt user's credential content.
// frontend
const { userEncryptionPublicKey } = await idOSClient.discoverUserEncryptionPublicKey(userId);
const ownershipProofMessage = "Please sign this message to confirm you own this wallet address";
const ownershipProofSignature = await ethereum.request({
method: "personal_sign",
params: [ownershipProofMessage, address],
});
// Report it back to your server
// e.g. await yourServer.report(userEncryptionPublicKey, ownershipProofSignature);
Step 3: Creating a User Profile
Once the public key is derived, you can create the user profile in idOS by passing it to the createUser function alongside with user id and the wallet the user's going to use to drive their idOS profile.
If the user doesn’t already have your credential, you can proceed to requesting a write grant so you can issue and write it.
[ frontend ] Requesting write grant
In order to write a credential to idOS, the issuer needs to obtain permission from the user. This can be done using a Delegated Write Grant (DWG).
A Delegated Write Grant (DWG) is a permission given by the user that allows a specific issuer to create a credential and it's copy for the issuer itself on the user's behalf. This is particularly relevant to not require the user to come back to your website if you want to add data to their profile. A DWG is a ERC-191 message that the user signs. The message contains fields:
* operation: delegatedWriteGrant
* owner: user_wallet_identifier
* consumer: grantee_wallet_identifier
* issuer public key: ed25519_public_key_hex_encoded
* id: _DWG_identifier
* access grant timelock: RFC3339_date_time_till_access_grant_will_be_locked
* not usable before: RFC3339_date_time_DWG_can_not_be_used_before
* not usable after: RFC3339_date_time_DWG_can_not_be_used_after
To do this, you must first to ask a user to sign DWG message:
const currentTimestamp = Date.now();
const currentDate = new Date(currentTimestamp);
const notUsableAfter = new Date(currentTimestamp + 24 * 60 * 60 * 1000);
const delegatedWriteGrant = {
owner_wallet_identifier: await signer.getAddress(),
grantee_wallet_identifier: signingKeyPair.address,
issuer_public_key: signingKeyPair.publicKey,
id: crypto.randomUUID(),
access_grant_timelock: currentDate.toISOString().replace(/.\d+Z$/g, "Z"), // Need to cut milliseconds to have 2025-02-11T13:35:57Z datetime format
not_usable_before: currentDate.toISOString().replace(/.\d+Z$/g, "Z"),
not_usable_after: notUsableAfter.toISOString().replace(/.\d+Z$/g, "Z"),
};
const message: string = await idOSClient.requestDWGMessage(delegatedWriteGrant);
const signature = await signer.signMessage(message);
Be sure you have the DWG message parameters and its signature kept. You need to use them on server side later.
[ backend ] Issuing and writing credentials
To issue a credential, you can use our W3C Verifiable Credentials helpers:
This will create a credential for the user in the idOS and a copy for you.
[ backend ] Revoking and editing credentials
The editCredential function allows issuers to update the public notes associated with a credential in the idOS. This is useful for actions like marking credentials as revoked or updating metadata.
In order for editCredential to work, the credential's public_notes field needs to be a valid JSON object with an id field, and the public_notes_id argument needs to have that value.
⚠️ Warning
If the new public_notes value doesn't have an id field, you'll stop being able to edit that credential.