/Legal/Transfer

Allows the client to transfer an account created using the Agent API to another application, such as Neuro-Access. If the account has an associated current Legal ID, the ID will also be transferred to the new application. To transfer an account, without Legal ID, the Key ID, and Key Signatures can be omitted. If transferring an account with any associated Legal ID, and its corresponding private key, the Key ID and Key Signatures must be provided.

JSON

Request

{
	"keyId": Optional(Str(PKeyId)),
	"nonce": Required(Str(PNonce)),
	"keySignature": Optional(Str(PKeySignature)),
	"requestSignature": Required(Str(PRequestSignature)),
	"pin": Optional(Str(PPin))
}

Response (if successful)

{
	"onboardingUri":Required(Str(POnboardingUri)),
	"qrCodeUrl":Required(Str(PQrCodeUrl)),
	"qrCodeWidth":Required(Integer(PQrCodeWidth>0)),
	"qrCodeHeight":Required(Integer(PQrCodeHeight>0))
}

XML

Request

<Transfer xmlns="https://waher.se/Schema/BrokerAgent.xsd"
          keyId=(Optional(Str(PKeyId)))
          nonce=(Required(Str(PNonce)))
          keySignature=(Optional(Str(PKeySignature)))
          requestSignature=(Required(Str(PRequestSignature)))
          pin=(Optional(Str(PPin))) />

Response (if successful)

<TransferCode xmlns="https://waher.se/Schema/BrokerAgent.xsd"
              onboardingUri=(Required(Str(POnboardingUri))) 
              qrCodeUrl=(Required(Str(PQrCodeUrl)))
              qrCodeWidth=(Required(Integer(PQrCodeWidth>0)))
              qrCodeHeight=(Required(Integer(PQrCodeHeight>0))) />

Input Parameters

Response Parameters

Note: The Onboarding URI can be transferred to the receiving application by different means. It can be converted to a QR code for instance, and scanned by the receiving application. You can use the QR Code API for this purpose (URL provided in the PQrCodeUrl property in the response), or you can generate the QR code by other means.

Note 2: Also note that once the account has been transferred, it will be unavailable via the Agent API. Any attempt to access it via the Agent API will result in an error, and repeated attempts may result in a temperorary block, and after persistant attempts, a permanent block.

Calculating the Key Signature

If providing a Key Signature, the signature in PKeySignature is calculated as follows. If not providing a Key Signature, PKeyId and PKeySignature can be left as empty strings in the following signature calculations.

1. Concatenate the strings PUserName ":" Host ":" PLocalName ":" PNamespace ":" PKeyId and call it s1, where Host is the host/domain name of the server. It is taken from the HTTP Host request header, so it must be the same as is used in the URL of the request. PUserName is the name of the account, used when creating the current account or logging in to the current account. PLocalName and PNamespace are the local name and namespace corresponding to the algorithm used for the key.

2. UTF-8 encode the secret corresponding to the key, and call it Key1.

3. UTF-8 encode the string s1, and call it Data1.

4. Calculate the HMAC-SHA256 signature using Key1 and Data1, and call it H1.

5. Base64-encode H1. The result is the key signature of the request.

Calculating the Request Signature

The signature in PRequestSignature is calculated as follows.

1. Concatenate the strings s1 ":" PKeySignature ":" PNonce ":" PPin, and call it s2. s1 is the intermediate result of computing the key signature in the previous step.

2. UTF-8 encode the secret corresponding to the account, and call it Key2.

3. UTF-8 encode the string s2, and call it Data2.

4. Calculate the HMAC-SHA256 signature using Key2 and Data2, and call it H2.

5. Base64-encode H2. The result is the signature of the request.

Javascript Library

Use the following asynchronous method in the Javascript Library, to call this resource. It computes the signatures according to the above specification.

var Response = await AgentAPI.Account.Transfer(LocalName,Namespace,KeyId,KeyPassword,AccountPassword,Pin);