(This document assumes that you are familiar with the general README. Reading README_Users won't hurt either.)
To start creating new Monit24.pl accounts for your users, you will need a distributor's account. Distributor's account (also called partner's account) is a special account that can be used for creating new user accounts. Distributor accounts are used only to create regular accounts: they cannot have services, groups or any other things that the regular accounts have. Distributors also cannot login to the Administration Panel, they can only access the API.
The Distributor API module can be used to manage distributor accounts.
To create a distributor's account, use the Distributor::Create method. Here is an example of calling this method:
{
"module":"Distributor",
"method":"Create",
"data":{
"login":"my_distributor_account",
"email":"test_distributor@monit24.pl",
"password":"d1str1_boot0R",
"contact_person":"John Smith",
"contact_phone":"123456789"
}
}
If the API method call succeeds, the response will contain your account's ID:
{"auth":{},"version":"2.0.0","error":null,"data":{"id":3461}}
To confirm that the account has been created properly, you can fetch the distributor's data with the Distributor::Read method:
{"module":"Distributor","method":"Read","auth":{"login":"my_distributor_account","password":"d1str1_boot0R"},"data":{"id":3461}}
If the response looks like this (particularly if the error is NULL):
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"contact_phone":"123456789",
"email":"test_distributor@monit24.pl",
"tax_id":null,
"address":null,
"contact_person":"John Smith",
"id":3461,
"login":"my_distributor_account"
}
}
then congratulations - you have successfully created your distributor account.
To create a new account, you will need to provide the following information:
A name for the account and default language for notifications and reports.
Each account has an exactly one user associated with it (in the future we will add the option to access one account by many users). Therefore when creating the account you need to provide the user's data: name, e-mail address, login and password. You can also specify other data, see the Account::Create method's documentation for details.
A package defines the account's limits: the number of monitored services, the minimal checks frequency, maximum allowed number of monitoring locations etc. As a distributor, you have access to some of the packages and when creating an account you have to choose one. To find out what packages can be used, call the Package::Find method:
{"module":"Package","method":"Find","auth":{"login":"my_distributor_account","password":"d1str1_boot0R"}}
The response will contain one package:
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"elements":[{
"min_locations_limit":2,
"min_interval":900,
"name":"demo",
"notification_channels":["email_extended","email_long","email_short","gadu_gadu","jabber"],
"id":632,
"max_locations_limit":3,
"max_services":3
}],
"total":1
}
}
By default, only very limited accounts are allowed (contact the Monit24.pl support, to add new packages to your account). This example "demo" package allows you to create accounts with the following limits:
The package also defines the available service types and their limits. You can fetch these for an individual package using the Package::Read method, you have to read the package with the service types:
{
"module":"Package",
"method":"Read",
"auth":{"login":"my_distributor_account","password":"d1str1_boot0R"},
"data":{
"id":632,
"with":["service_types"]
}
}
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"min_locations_limit":2,
"min_interval":900,
"name":"demo",
"notification_channels":["email_extended","email_long","email_short","gadu_gadu","jabber"],
"id":632,
"max_locations_limit":3,
"max_services":3,
"service_types":[
{"min_interval":900,"name":"http","id":1,"max_services":3},
{"min_interval":900,"name":"smtp-helo","id":2,"max_services":3},
{"min_interval":900,"name":"https","id":5,"max_services":3},
{"min_interval":900,"name":"ping","id":7,"max_services":3},
]
]
}
(these limits do not mean that the package allows 12 services, the total services limit is in the package's max_services)
Note that after creating an account, it's package can be changed only by the Monit24.pl administrators.
Once you have all the required data for the account, you can create it with the Account::Create method:
{
"module":"Account",
"method":"Create",
"auth":{"login":"my_distributor_account","password":"d1str1_boot0R"},
"data":{
"login":"test_user",
"password":"p4ssword",
"package_id":632,
"name":"Test account",
"email":"test_account@monit24.pl",
"contact_person":"Test Test",
"language":"en"
}
}
The response will contain the new account's ID:
{"auth":{},"version":"2.0.0","error":null,"data":{"id":4844}}
Before the account can be used, it needs to be activated. To do it, use the Account::Activate method:
{"module":"Account","method":"Activate","auth":{"login":"my_distributor_account","password":"d1str1_boot0R"},"data":{"id":4844}
Now the account is active and the user can login to it:
{"module":"User","method":"Read","auth":{"login":"test_user","password":"p4ssword}}
{
"auth":{},
"version":"2.0.0",
"error":null,
"data":{
"contact_phone":"",
"language":"en",
"contact_person":"Test Test",
"last_login_ip":null,
"last_login_timestamp":null,
"login":"test_user2",
"email":"test_account@monit24.pl",
"tax_id":null,
"address":null,
"id":4845
}
}
The new account has a default group created. Also, notifications for this group will be sent to the e-mail address specified while creating (in this case test_account@monit24.pl). You can change the notification addresses by using the NotificationAddress API module.
Distributors are allowed to call API methods on their users' objects.
For example, to list all services for all your users, call the Service::Find method with the distributor's authentication data.
Almost all calls work the same, but some may impose stricter requirements than they do when called as a regular user. For example, when creating a new group you have to specify the account it will be assigned to (when creating as an user, the user's account is used) and when creating a service you have to specify its group (it defaults to the user's default group when creating as an user).
To block an account use the Account::Block method. Blocked accounts cannot be accessed by users, all their services are paused and all objects (services, groups, addresses etc.) become invisible and cannot be modified (even by distributors). However, the blocked accounts will appear in distributor's Account::Find output, with the blocked attribute set to 1.
Blocked accounts can be unblocked by calling the Account::Unblock method. Unblocking restores the access to the account, but the services have to be unpaused separately.
Distributors can delete the accounts with the Account::Delete method. This permanently deletes the account with all its services, groups, addresses etc. Use with caution.