If you are implementing a service that will access a MoneyWorks database via its REST interface hosted on a MoneyWorks Now server, you can retrieve the necessary login credentials by querying the MoneyWorks Now login gateway.
A MoneyWorks Datacentre REST query requires Authorization headers for the realms "Datacentre" and "Document", as outlined in http://cognito.co.nz/developer/moneyworks-datacentre-rest-api/ and http://cognito.co.nz/developer/accessing-restserver-from-php/.
That is you need a folder username and password (this is the Datacentre realm), a document name, and a document username and password. You also need to know the domain name of the host on which the document resides. It is possible that the host for a database may change (if for example it is relocated to a server that is nearer its users). Such a relocation is transparent to normal MoneyWorks Now users, because MoneyWorks looks up the login credentials from the MoneyWorks Now gateway every time a user logs in. If you are implementing a service that interfaces to a MoneyWorks database, then you will need to do this lookup and cache the results.
Setting up access
The owner of the document should set up a username in the document and grant it access via MoneyWorks Now. If you are implementing a service, ideally the MoneyWorks Now account used for this should be one that is specific to your service. For example, let us imagine that you are providing a bank statement feed service into the document owned by Acme Widgets Ltd. You should create a MoneyWorks Now account called say "feedservice_acme@yourcompany.com". The document owner (Acme Widgets) would set up a user in their document called "Bank Feed", and assign login privileges to your MoneyWorks Now account. The user in the document will be assigned a password (usually randomly generated). The document will also be located within Acme's hosting account which will have a folder name and associated password. A mobile app, on the other hand, will probably log in using the user's own regular MoneyWorks Now login.
All you need to know in order to log in to their document is the MoneyWorks Now account name and its password.
The login gateway is located at
https://api.moneyworks.net.nz/mwnow/get_docs.php
To query the gateway, make a POST request with parameters "user" and "pass".
e.g.
curl --data "user=feedservice_acme@yourcompany.com&pass=secret" "https://api.moneyworks.net.nz/mwnow/get_docs.php"
The return from the server will be UTF8 text in much the same format as an HTML header. i.e lines consisting of a data field name followed by a colon followed by one space followed by a value and terminated by a CRLF.
status: ok count: 1 host_1: mwnow2.moneyworks.net.nz port_1: 6710 folderuser_1: MWNow/Test3 folderpass_1: F7%6P%B5XAVW8X+ZXBUU docname_1: Acme3.mwd7 company_1: Acme Widget Ltd docuser_1: Bank Feed docpass_1: 98427ndupefhulkdaIG etc...
The status will be "ok" on success, otherwise "fail".
Make no assumptions about the ordering of the rows. There may also be additional data field rows not documented here which should be ignored.
If there are multiple document logins associated with the account, the response may contain multiple entries with a count greater than 1 (the next entry would be host_2, folderuser_2, etc. The number of entries is denoted by the count field. If there are multiple entries, you will need to select the entry for the docname that you intend to log in to.
Alternatively, you may add &format=json to the post params to get JSON formatted results
"status" : "ok",
"docs" : [
{
"host" : "mwnow2.moneyworks.net.nz",
"port" : 6710,
"folderuser" : "MWNow/Test3"
"folderpass" : "F7%6P%B5XAVW8X+ZXBUU"
"docname" : "Acme3.mwd7"
"company" : "Acme Widget Ltd"
"docuser" : "Bank Feed"
"docpass" : "98427ndupefhulkdaIG"
},
{
"host" : "mwnow3.moneyworks.net.nz",
"port" : 6710
"folderuser" : "ABC"
etc
}
...
]
The folderuser and folderpass are the Datacentre realm credentials. The docuser and docpass are the Document realm credentials. The docname is the document name to use in the request url. And of course the host is the server to which you should address your REST requests.
It will be rare for the address and credentials to change, so it is not necessary to look them up every time you need to make a request of the REST API. You should cache the credentials. The login server may apply strict rate limiting to requests, so do not depend on it to respond to multiple requests for the same account in quick succession.
In the event of status = fail, there will be a reason.
e.g.
status: fail reason: Incorrect username or password
or
status: fail reason: Retrying too soon after previous login attempt