The WatchMouse API supports two types of access:

• Anonymous access
• Session-based access.

Some calls support both type of access while others support only one. Obviously, calls that affect your account are available only with session based access.

Anonymous access

Several calls allow anonymous access. For example the info_ip call can be used without authenticating first.

   Try the info_ip call now.

The anonymous calls may have more strict usage limitation. At this time, the limit is set to 50 "credits" (see below) per day. You can find the number of remaining credits by calling acct_credits.

The WatchMouse API implements anonymous access with a kind of session key too: one that is assigned on the fly and belongs to exactly one IP address. This is visible in the call as well: there will still be a nkey parameter, but it is optional, like in the info_ip call. You can even find the anonymous nkey in a cookie sent by the API, see below.

Session based access.

Session based access is typically used when the call affects an account and authentication is needed. But if you have an account with WatchMouse,  it makes sense to uses sessions for other calls as well, as the limits for the calls are more generous than for anonymous access.
A typical flow for a session would be

1. acct_login - provide account and password, and obtain a session key
2. ...calls to manipulate the account, providing the session key nkey in each call...
3. acct_logout - provide the session key to clean up
   

Note: this last step should not be omitted as there is a limit to the number of active sessions per account.
Note: sessions will expire after 15 minutes of inactivity (i.e. not used in a API call). You may wish to call acct_noop to keep a session active

Access to other accounts.

For retrieving information from an account (logs, statistics, graphs, ...), the following authorization applies

• The owner can access all information of their account and their sub-accounts.
  
• A reseller can access all information of their account and their clients' accounts.
• The owner can explicitly authorize other accounts to access all information of a specific folder, or for all folders.
• The owner can explicitly authorize anonymous read access to a specific folder.
• No-one else can access the information.*
  

For manipulating object like monitoring rules, contacts, and folders, the following authorization applies:

• The owner can manipulate all information of their account and their sub-accounts.
• A reseller can manipulate all information of their account and their clients' accounts.
• No-one else can manipulate the said information.
  

*) with one exception: The rule_banner call will show the uptime percentage of any rule, give its ID. As the ID cannot be traced back to a specific rule / account, this is thought to be acceptable.

Cookies used by the API.

The API will send a nkey cookie upon authentication (via acct_login) or when accessed anonymously. Also, the nkey can be sent in a cookie instead of as a parameter to each call. This is useful in testing, but probably less useful in practice. One would assume that this could be used in JSONP type calls, but it turns out not all browsers send the cookies in that situation.

API calls and credits.

Each call to the WatchMouse API is associated with a price, expressed in "credits". And the API distinguishes several "currencies" (credit types).
At this time, the following credit types are recognized

• 'api' credits - normal type of credits. Each account in the WatchMouse system has at least 200 credits per day, but with higher subscriptions, you will see higher limits too.
  
• 'sms' credits - credits used to send out text messages (SMS) via one of our gateways with our SMS providers and telco's.
  
• 'check' credits - credits used by call that involve the WatchMouse monitoring stations. So when you issue a cp_check or rule_check call, it will deduct from this credit type
  
• 'page' credits - credits used to send ot pager messages via our pager gateway (only available in Benelux. Other pagers via SMS or email gateway)
  
• 'scan' credits - credits used for vulnerability scans
  

Note: Each call has it's own price: some are free, some will be 1 api credit or 1 check credit, but it can also be a fraction, like 0.1 api credit, or a multiple, like 3 check credits. Please see the detailed documentation of each call for the exact cost.

Next: Using the API