Skip to main content

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',
});
Always pass apiBaseUrl

Pass apiBaseUrl: 'https://cloudwallet.hovi.id' every time you create a CloudWallet.

Options​

ParameterTypeDescription
apiKeystring (Optional)Your Cloud Wallet API key. Needed to create and list wallets.
walletAccessTokenstring (Optional)A wallet's access token. Needed for every call that acts on that wallet.
apiBaseUrlstring (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.

note

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:

  1. Create a CloudWallet instance with your Cloud Wallet API key.
  2. Create a wallet for each user with createWallet(). The response contains the wallet's accessToken.
  3. Call setWalletAccessToken() with a wallet's token to act on that wallet.
  4. 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>' });
tip

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);
}