Consumer guide
Last updated
Last updated
The primary features provided by the Consumer SDK are:
checking if your user has an idOS profile and an adequate credential;
requesting access to user credentials, with an optional timelock to prevent premature access revocation;
retrieving and verifying credentials you've been granted access to;
listing all access grants you've been given by your users;
implementing a Passporting-compliant onboarding flow.
See for more context, and discuss with your compliance officer:
which credential Issuers are you open to trusting;
how long, if at all, you need to retain access to user data;
whether you’re going to be using Passporting.
🛑 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:
recipientEncryptionPrivateKey
: base64-encoded nacl.BoxKeyPair
secret key. It'll be used to decode the credential copies that the owners (users) share with you by creating access grants.
see Encryption for more information
consumerSigner
: this can be a NEAR KeyPair
, or an ethers.Wallet
. This will be used to sign RPC calls to the idOS nodes.
see Signatures for more information
Your frontend (web or native app), as your user’s touch point, is where you’ll:
confirm that the user is in idOS;
find whether the user has an adequate credential;
request an access grant to user credentials.
Your backend (private server) is where you’ll:
retrieve user credentials you’ve been granted access to;
list the access grants you’ve been granted.
Get our NPM packages
https://www.npmjs.com/package/@idos-network/client
https://www.npmjs.com/package/@idos-network/consumer
and their dependencies with pnpm (or your package manager of choice)
Connect your user's wallet however you do it today, for example:
Get your user's address from the signer above and confirm they have an idOS profile. If not, redirect them to your Issuer. If you have an IDV integration, you can yourself be the issuer. See the Issuer Guide for more information.
Pass your user’s signer to the SDK, so it knows where to send signature requests to.
Access Grants queries can also be paginated:
Optionally, you can double check that the existing access grant matches your requirements. You do this on your backend.
If you don’t have an access grant, you can proceed to filtering the user’s credentials and requesting one or more access grants.
TODO: missing extraction into Client SDK
https://github.com/idos-network/idos-sdk-js/blob/cd0605a4e545836a6d9fc4751a31c142fc28fd8c/packages/%40controllers/src/isle/index.ts#L460-L486
The simplest way to do this is to ask the user to create and insert an access grant for you.
TODO: missing extraction into Client SDK
https://github.com/idos-network/idos-sdk-js/blob/cd0605a4e545836a6d9fc4751a31c142fc28fd8c/packages/%40controllers/src/isle/index.ts#L341-L369
Alternatively, you can ask for a delegated access grant, which the user creates:
and you then insert after sending it to your backend:
Using passporting
TODO: missing code examples for passporting:
ask for credential duplicate (C1.2) separately and before asking for AG
get hash from C1.2 and use it on dAG request
send dAG to own backend, which proxy sends to OE1's passporting server
If you're using passporting:
If you need a helper to verify that the W3C VC is something you want to trust, here's an example: