/Account/Recover

Allows a user to recover its account, given that it can provide either the user name or personal number, in combination with either the e-mail address or phone number used when creating a legal identity on the account. No authentication is required in the request. If information match, any of the following may happen:

• If the account has no assets (eDaler®, Neuro-Features™, etc.), and no legal identities registered, a recovery e-mail will be sent to the e-mail registered with the account. The e-mail will contain a clickable QR-code that will allow the agent app to recover the account, using the method outlined below.

• If the account has a peer-reviewed legal identity, signature requests will be sent to the peers, to confirm you are trying to recover the account. The user should contact the peers to prepare them for the recovery procedure, so they can receive it and authorize access to the account.

• If the account is approved by the operator of the Neuron®, a notification will be sent to the operator, that the user tries to recover its account. The user should contact the Neuron® operator to continue the recovery procedure.

Note: Any registered legal identities on the account will be assumed to be compromized. After recovery of account, a new legal identity must be created.

Note 2: The call is subject to login-audit rules, and the client can become temporarily blocked if calling resource too frequently. Abuse can lead to permanent block of client.

Note 3: For reasons of security, no information is returned to the caller, indicating if the request was successful or not, or how to proceed with the recovery. If messages were sent, they will be received by recipients, and processed accordingly. There is one exception to this rule: If account name is not provided, and personal number and country is provided, and multiple accounts exist on the server, an HTTP 422 Unprocessable Entity error is returned. If this happens, the client must specify an account name to recover account.

Note 4: The client does not have to create a session to access this resource. Other applications (such as those using an XMPP connection to connect to the network) can also use this resource to recover accounts.

JSON

Request

{
	"userName":Optional(Str(PUserName)),
	"personalNr":Optional(Str(PPersonalNr)),
	"country":Optional(Str(PCountry)),
	"eMail":Optional(Str(PEMail)),
	"phoneNr":Optional(Str(PPhoneNr))
}

Response (if successful)

{
}

XML

Request

<Recover xmlns="https://waher.se/Schema/BrokerAgent.xsd"
         userName=(Optional(Str(PUserName)))
         personalNr=(Optional(Str(PPersonalNr)))
         country=(Optional(Str(PCountry)))
         eMail=(Optional(Str(PEMail)))
         phoneNr=(Optional(Str(PPhoneNr))) />

Response (if successful)

<RecoverResponse xmlns="https://waher.se/Schema/BrokerAgent.xsd" />

Input Parameters

obinfo URI scheme

The recovery e-mail will contain a clickable QR-code that an agent application can use to recover the account. The URI in the code uses the URI scheme obinfo, and will only be valid for a couple of days. It has the following syntax:

obinfo:DOMAIN:CODE:KEY:IV

There are five parts:

1. URI Scheme. This is the literal obinfo.
2. A Domain name of a Neuron® that can provide the onboarding information to the client.
3. A Code necessary to access the onboarding information. This code is base64-encoded.
4. A key used for encrypting the onboarding information. This key is base64-encoded.
5. An Initiation Vector (or IV) used for encrypting the onboarding information. This IV is base64-encoded.

Once the URI has been received, the Agent Application proceeds as follows, to gain access to the account:

1. Get the encrypted information linked to by the URI.

   1. Form an URL to the information as follows: https://DOMAIN/Onboarding/GetInfo, where DOMAIN must be replaced with the value received in the obinfo URI earlier.

   2. Perform a HTTP POST request to the URL. Send the CODE as content using Content-Type: text/plain. This code must be untouched (i.e. don’t base64 decode it). The request must also add an Accept: text/plain header to the request.

   3. The response to the request, is a base64 encoded encypted BLOB.

2. Decrypt the information.

   1. Base64-decode the response from the previous step.

   2. Use AES, together with Cipher Block Chaining (CBC) and PKCS7 padding, as well as the base64-decoded KEY and IV from the obinfo URI above.

3. The result will be an XML document containing the onboarding information required to recover the account. It will have the following format:

   <Account xmlns='http://waher.se/schema/Onboarding/v1.xsd'
            domain='DOMAIN'
   		 userName='USERNAME'
   		 password='PASSWORD'/>
   

   The information in the XML document can be used to gain access to the account again.

Note: A reference implementation for handling the obinfo URI scheme can be found in the ID App repository. Search for ScanQRCode(). The implementation also supports invitation to create accounts on different Neurons, as well as transferring the credentials from one app to another (for instance, when changing a phone, and transferring the identity from the old phone to the new phone).

Note 2: A client should change the password once the account has been recovered.

Javascript Library

Use the following asynchronous method in the Javascript Library, to call this resource.

var Response = await AgentAPI.Account.Recover(UserName,PersonalNr,Country,EMail,PhoneNr);