The Upvest Blockchain API

A multi-protocol blockchain API for building blockchain-interacting applications.

Get Started     Tutorial     API Reference

User Account Recovery

Learn how to reset user account passwords and recover accounts

In case the user forgets their password, there's the option to perform a password reset, and recover their account, using their unique Recovery Kit.

The Recovery Kit

The Upvest Recovery Kit is a doubly-encrypted artifact that contains a combination of encrypted metadata (used primarily for KYC purposes), and additional data that enables Upvest to restore the private keys of that user. Due to the way the Recovery Kit is encrypted, it is no longer considered a particularly sensitive asset (unlike conventional seeds and private keys), making it much easier and safer to handle and store for end users.

The cryptographic keypair used to encrypt and decrypt recovery kits is called the Recovery Kit Encryption Keypair (composed of a Recovery Kit Encryption Key and Recovery Kit Decryption Key), which is created by the Upvest customer. As such, the Recovery Kit can only be decrypted with your Recovery Kit Decryption Key, which makes it the most crucial part of your implementation with Upvest. We highly recommend to contact us via [email protected] with any specific questions.

Obtaining the Recovery Kit Keypair

In order to test the recovery process in the Upvest Playground (i.e. testnet) environment, you can directly retrieve the Recovery Kit Decryption Key from your Upvest Dashboard via the API keys section.

This particular key is generated by Upvest for simplicity, and is for testing purposes only. When you want to migrate to the Live (i.e. mainnet) environment, it is mandatory that you generate the Recovery Kit Encryption Keypair on your side in a secure environment, and provide the Recovery Kit Encryption Key to Upvest. The instructions for this process can be found in this knowledge base article.

The format for the Recovery Kit Encryption Keypair is a Curve25519, XSalsa20 and Poly1305 keypair. These can be generated using Libsodium (or NaCl). To make this process as convenient as possible, we have created a script that generates a Recovery Kit Encryption Keypair for you. Please git clone and execute it locally, from a safe environment. Follow the instructions from the repository's readme.

Once you’ve generated your keypair, make sure to carefully copy the entire Recovery Kit Decryption Key output to a safe place. We recommend storing it with a trustee as well so that in any case, users will be able to recover their assets. Make sure to copy the entire key carefully.

Before you start using Upvest wallets with production users, be sure to test the recovery (i.e. password reset) process thoroughly so that you are assured that it will work when needed.

Recovery Process

Upon user creation, Upvest will send you the user's Recovery Kit (represented as a QR code), for you to pass onto your user in whichever form you choose.

If the user forgets the password for unlocking their wallet, they can come to you with this Recovery Kit. In order to reset the password, which is essentially restoring the private key and encrypting it with a new password, the steps outlined below need to be taken:

Reading and Decrypting the Recovery Kit

The Recovery Kit is represented in the form of a QR code (the bytes of which represent an encrypted Protobuf). Once the user supplies you with their Recovery Kit, you need to parse this QR code and decrypt the first layer of encryption (using your your Recovery Kit Decryption Key) in order to retrieve the Recovery Kit’s metadata.

Upvest provides an soon-to-be open source tool (“Dakota”) that can be used to read the recovery kit QR code, and perform the decryption using the Recovery Kit Decryption Key. This is just a sample application, and the functionality therein can be reimplemented within your application if desired.

A test version of Dakota is available here for convenience, however this should only be used with Playground recovery kits, as using it for Live recovery kits may compromise your decryption key and the recovery kits themselves. For testing Live environment, we recommend deploying your own internal instance of Dakota.

Sample Content of a Decrypted Recovery Kit

{
  "seed": {
    "cipher": "x25519-xsalsa20-poly1305",
    "cipherparams": {
      "ephemeralpk": "wbMsFDoCb1txHfwXRjx1NNhY/AFjlpBegAlOkd7oMw0=",
      "nonce": "7ZXNDrgdojVZ0vDodFZuRA8apSDVgzXGB",
      "recipient": "IFmQgssEx58RMdmOzPvdMldtcKQvYfdRpNbb63fm69F0="
    },
    "ciphertext": "e/3HZ+PrYF3+weqbHUewdOBOXLaVx44UzOZ4PlE+Ux7p6GBM2k5i09kErdrHYD6R",
    "hash": "N3UTtCDJU+0raOIlnheEjg==",
    "hashfunction": "argon2id",
    "hashparams": {
      "len": 16,
      "m": 65536,
      "p": 4,
      "salt": "xJrIuOHb218EEqjOTzRWWQ==",
      "t": 33,
      "v": 19
    }
  },
  "seedhash": "N3UTtsdfDJU-0raOIlnheEjg",
  "username": "2|upvest_test_kit!|0",
  "datetime": "1550835009",
  "clientIp": "127.0.0.1",
  "version": "api-unknown",
  "userAgent": "Not/Set by Caller",
  "userId": 660
}

Resetting the User's Password

In order to reset this user's password and recover their account, send the seed, seedhash , and user_id from the above output, together with the user’s new desired password to the /tenancy/recover/ endpoint.

The Upvest platform will then be able to decrypt the seed and regenerate all of the user’s wallets, which will then be re-encrypted using the user's new password, and then stored using our secure process.

Updated 3 months ago


User Account Recovery


Learn how to reset user account passwords and recover accounts

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.