/Legal/ApplyId

Allows the client to apply for a new Legal Identity on the server. The application must be signed using one of the keys created by the client.

JSON

Request

{
	"keyId": Required(Str(PKeyId)),
	"nonce": Required(Str(PNonce)),
	"keySignature": Required(Str(PKeySignature)),
	"requestSignature": Required(Str(PRequestSignature)),
	"Properties":
	{
		"name": Required(Str(PPropertyName)),
		"value": Required(Str(PPropertyValue))
	}?[]
}

Response (if successful)

{
	"Identity": Required(PIdentity)
}

XML

Request

<ApplyId xmlns="https://waher.se/Schema/BrokerAgent.xsd"
         keyId=(Required(Str(PKeyId)))
         nonce=(Required(Str(PNonce)))
         keySignature=(Required(Str(PKeySignature)))
         requestSignature=(Required(Str(PRequestSignature)))>
    <Properties>
        <[
        <Property name=(Required(Str(PPropertyName)))
                  value=(Required(Str(PPropertyValue))) />?[]
        ]>
    </Properties>
</ApplyId>

Response (if successful)

<IdentityResponse xmlns="https://waher.se/Schema/BrokerAgent.xsd">
	<[Required(PIdentity)]>
</IdentityResponse>

Input Parameters

Note: The ApplyId resource requires the request include the Referer (sic.) HTTP Header. The value of the Referer header is typically set by the browser, if the call comes from a Browser, and contains a URL to the page originating the call. The Referer URL gets engraved into the generated identity, using the AGENT meta-data tag. For embedded calls, the Referer header must be set explicitly by the caller. It should typically contains a reference to the executable (for instance the Assembly name and version), an URL to the product page or repository containing the code.

Response Parameters

Calculating the Key Signature

The signature in PKeySignature is calculated as follows.

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 followed by ":" PPropertyName ":" PPropertyValue for each property, in the same order as provided in the request, 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.Legal.ApplyId(LocalName,Namespace,KeyId,KeyPassword,AccountPassword,Properties);

Note The Properties argument is a normal JSON dictionary, not an array. Properties in this dictionary are instead enumerated and converted to the format expected by the web service.