/Account/Create

Creates an agent account on the server (and logs in to it). This account can be used when logging in, using the Agent API, but also to connect to the Neuron® using any of the available XMPP bindings available. The account that is created, is considered a regular XMPP account on the broker.

When first created, the account is in a disabled state. You need to validate the e-mail address provided in the request first, before the account can be enabled. An e-mail with a verification code will be sent to the e-mail address provided in the request.

Security Notice: This resource requires an API Key and Secret to be provided. These are requested from the operator and must be protected. If compromized, the operator can choose to disable the key. This resource should therefore only be used by clients that can protect such credentials. If creating an account in an environment where protecting such credentials is not possible (such as a web page running on a client browser), use the CreateWebForm resource instead. Eacn API Key is given a number of accounts that can be created with that key. If that limit is reached, no more accounts can be created using that key, until the limit is increased or existing accounts created by that API Key is deleted.

JSON

Request

{
	"userName":Required(Str(PUserName)),
	"eMail":Required(Str(PEMail)),
	"phoneNr":Optional(Str(PPhoneNr)),
	"password":Required(Str(PPassword)),
	"apiKey":Required(Str(PApiKey)),
	"nonce":Required(Str(PNonce)),
	"signature":Required(Str(PSignature)),
	"seconds":Required(Int(0 < PSeconds <= 3600))
}

Response (if successful)

{
	"created":Required(DateTime(PCreated)),
	"enabled":Required(Bool(PEnabled)),
	"canRelay":Required(Bool(PCanRelay)),
	"jwt":Required(Str(PJwt)),
	"expires":Required(DateTime(PExpires))
}

XML

Request

<CreateAccount xmlns="https://waher.se/Schema/BrokerAgent.xsd"
               userName=(Required(Str(PUserName)))
               eMail=(Required(Str(PEMail)))
               phoneNr=(Optional(Str(PPhoneNr)))
               password=(Required(Str(PPassword)))
               apiKey=(Required(Str(PApiKey)))
               nonce=(Required(Str(PNonce)))
               signature=(Required(Str(PSignature)))
               seconds=(Required(Int(0 < PSeconds <= 3600))) />

Response (if successful)

<AccountCreated xmlns="https://waher.se/Schema/BrokerAgent.xsd"
                created=(Required(DateTime(PCreated)))
                enabled=(Required(Bool(PEnabled)))
                canRelay=(Required(Bool(PCanRelay)))
                jwt=(Required(Str(PJwt)))
                expires=(Required(DateTime(PExpires))) />

Input Parameters

Response Parameters

Note: If trying to create an account that already exists, and that is enabled, but using the same password as the existing account, and if PLAIN authentication is permitted on the server, the request will be treated as a login request. The timestamp of the creation of the account can be seen in the response to the request.

Restrictions on User Names

User Names are strings. Not all strings are accepted as user names however. The following restrictions apply:

• User names cannot be empty.
• User names must not be longer than 1023 characters.
• The following characters are not permitted, to allow use of the account in XMPP: ", &, ', /, :, <, > and @.
• White-space characters (character codes 0-32) are not allowed.
• Characters that are prohibited in file names are also not allowed: |, *, ? and \.

Calculating Signature

The signature in PSignature is calculated as follows.

1. If a phone number is not provided, you concatenate the strings PUserName ":" Host ":" PEMail ":" PPassword ":" PApiKey ":" PNonce and call it s, 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.

   If a phone number is provided, you concatenate the strings PUserName ":" Host ":" PEMail ":" PPhoneNr ":" PPassword ":" PApiKey ":" PNonce and call it s.

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

3. UTF-8 encode the string s, and call it Data.

4. Calculate the HMAC-SHA256 signature using Key and Data, and call it H.

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

Signature Audits

Signatures are audited. If too many failed signature attempts are received in a row from a given remote endpoint, that endpoint will be temporarily blocked from further attempts. Error message will contain a timestamp when new attempts can be made. If continuing failing, a remote endpoint may become permanently blocked from accessing the API.

Alternative Name Suggestions

If unable to create an account, suggestions for alternative account names will be returned as HTTP headers, with header names X-AlternativeNameN, where N is a random number starting with 1. Digits will be two or more digits.

Javascript Library

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

var Response = await AgentAPI.Account.Create(UserName,EMail,PhoneNr,Password,ApiKey,Secret,Seconds);

Note: If creation of account is successful, the API library will maintain the resulting token, and make sure to refresh it regularly.