Authentication
The Cloud Wallet SDK uses two kinds of credentials:
- Cloud Wallet API key – You get it from Hovi Studio (see Get a Cloud Wallet API key). It's used only to create wallets and list them.
- Wallet access token – You get it when you create a wallet. Every other call acts on one wallet, such as accepting a credential offer or submitting a presentation, and needs that wallet's access token.
Initialization
import { CloudWallet } from '@hovi/cloudwallet-sdk';
const wallet = new CloudWallet({
apiKey: '<YOUR_CLOUD_WALLET_API_KEY>',
apiBaseUrl: 'https://cloudwallet.hovi.id',
});
Pass apiBaseUrl: 'https://cloudwallet.hovi.id' every time you create a CloudWallet.
Options
| Parameter | Type | Description |
|---|---|---|
| apiKey | string (Optional) | Your Cloud Wallet API key. Needed to create and list wallets. |
| walletAccessToken | string (Optional) | A wallet's access token. Needed for every call that acts on that wallet. |
| apiBaseUrl | string (Optional) | The base URL of the Cloud Wallet API. Set it to https://cloudwallet.hovi.id. |
Pass at least one of apiKey or walletAccessToken, or the constructor throws an error.
You can create one CloudWallet instance and use it everywhere in your application.
Authentication methods
You can set or change the credentials after you create the instance.
setApiKey(apiKey: string)
Sets the Cloud Wallet API key.
await wallet.setApiKey('<YOUR_CLOUD_WALLET_API_KEY>');
setWalletAccessToken(walletAccessToken: string)
Sets the wallet access token. The calls that follow act on that wallet.
await wallet.setWalletAccessToken('<WALLET_ACCESS_TOKEN>');
How it fits together
An ecosystem has one Cloud Wallet API key and can have many wallets:
- Create a
CloudWalletinstance with your Cloud Wallet API key. - Create a wallet for each user with
createWallet(). The response contains the wallet'saccessToken. - Call
setWalletAccessToken()with a wallet's token to act on that wallet. - To act on another wallet, set that wallet's token.
Example
import { CloudWallet } from '@hovi/cloudwallet-sdk';
// Step 1: initialize with your Cloud Wallet API key
const wallet = new CloudWallet({
apiKey: '<YOUR_CLOUD_WALLET_API_KEY>',
apiBaseUrl: 'https://cloudwallet.hovi.id',
});
// Step 2: create two wallets
const wallet1 = await wallet.createWallet({ label: 'Jane', secret: '<WALLET_SECRET_1>' });
const wallet2 = await wallet.createWallet({ label: 'John', secret: '<WALLET_SECRET_2>' });
// Step 3: act on wallet1
await wallet.setWalletAccessToken(wallet1.response.accessToken);
await wallet.acceptCredentialOffer({ protocol: 'openid', credentialOfferUri: '<CREDENTIAL_OFFER_URI>' });
// Step 4: switch to wallet2
await wallet.setWalletAccessToken(wallet2.response.accessToken);
await wallet.acceptCredentialOffer({ protocol: 'openid', credentialOfferUri: '<CREDENTIAL_OFFER_URI>' });
Store each wallet's access token securely with the user it belongs to, so you can switch to their wallet with setWalletAccessToken().
Error handling
When a call fails, the SDK throws a standard Error. Its message includes the HTTP status and the reason, for example Axios Error 401: …. Wrap your calls in try/catch:
try {
const credentials = await wallet.getStoredCredentials();
} catch (error) {
console.error((error as Error).message);
}