If you haven't done so already, we recommend reading the Kotobee API Introduction.


The User API lets you control all aspects of users for your cloud ebook or library. Possible operations are adding, editing, and deleting users.



Add user


https://www.kotobee.com/api/v1/user/add

Add a new user into the system, or add additional access to an existing user. Available variables are as follows.

serial
Contains your serial number
email
The email of the new user
pwd
A password to set for the new user (optional)
uid
User ID. You may use the user ID instead of the email, if you would like to add additional access to an existing user
libid
The library ID, in case the user will be a global user (has access over everything)
catid
The category ID, in case the user will have permission over a certain category. This variable is available for libraries only
bid
The book ID, in case the user will have permission over a certain book. This variable is available for libraries only
cid
The cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the past three variables (libid, bid, catid) will take effect
active
If value is 1, then user will be activated straight away after creation
noemail
If value is 1, then no email will be sent to the user. This can't be used if active variable is 0
activationemail
If value is 1, then user will be sent an email with the activation link after creation. This can't be used if active variable is 1


Here's an example that add a user by email (newuser@gmail.com), sets a password (mysecretpwd), activates the account, and assigns permissions to the library with ID 42:

https://www.kotobee.com/api/v1/user/add?serial=1234-5678-9999-9999&email=newuser@gmail.com&pwd=mysecretpwd&libid=42&active=1


An example of how to do it using POST variables with PHP:

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER => 1,
  CURLOPT_URL => "https://www.kotobee.com/api/v1/user/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_SSL_VERIFYPEER => false,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POST => true
));

$data = array();
$data["serial"] = "1234-5678-9999-9999";
$data["email"] = "newuser@gmail.com";
$data["pwd"] = "mysecretpwd";   //must be at least 6 characters
$data["libid"] = "42";
$data["active"] = "1";
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);

$resp = curl_exec($curl);
//echo $resp;     //in case you want to view the result
curl_close($curl);

You may add multiple permissions to the same user across multiple API calls. Each request is considered as a separate "add" operation.

 

Edit user

    

https://www.kotobee.com/api/v1/user/edit 

 

 Edit an existing user. Available variables are as follows.  
     
serial 
Contains your serial number
email 
The email of the existing user
pwd 
A password to reset for the new user (optional)
uid
The user ID to identify the user instead of the email
libid 
The library ID, in case the user will be a global user (has access over everything)
catid 
The category ID, in case the user will have permission over a certain category. This variable is available for libraries only
bid 
The book ID, in case the user will have permission over a certain book. This variable is available for libraries only
cid 
The cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the past three variables (libid, bid, catid) will take effect
active 
If value is 1, then user will be activated straight away after creation
noemail 
If value is 1, then no email will be sent to the user. This can't be used if active variable is 0
activationemail 
If value is 1, then user will be sent an email with the activation link after creation. This can't be used if active variable is 1
     

Here's an example that deactivates a user from the system:

    

https://www.kotobee.com/api/v1/user/edit?serial=1234-5678-9999-9999&email=existinguser@gmail.com&active=0     

  


 Delete user
    

https://www.kotobee.com/api/v1/user/delete 

 

Delete an existing user entirely, or remove access to an entity (library, category, or book). Available variables are as follows. 


serial 
Contains your serial number
email 
The email of the existing user 
libid 
The library ID, in case you want to remove user access from the library (globally)
catid 
The category ID, in case you want to remove user access from a certain category 
bid 
The book ID, in case you want to remove user access from a certain book
cid
The cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the past three variables (libid, bid, catid) will take effect  
deleteall
If value is 1, then the user will be deleted entirely from the system

   

Here's an example that deletes the user entirely:

http://www.kotobee.com/api/v1/user/delete?serial=1234-5678-9999-9999&email=existinguser@gmail.com&deleteall=1



Error codes 

The following errors codes may be returned by the API depicting various meaning

  

s_authError

The serial number used is not registered with Kotobee Cloud
s_wrongUser

The library or cloud ebook you are trying to reach cannot be accessed by your serial number
s_emailBlank

No email was provided when adding a new user
s_userIdMissing

No email or user ID was provided, to identify an existing user
s_emailAlreadyRegistered

When adding a new user, the email is already registered
s_userNotRegistered

When requesting an edit or delete operation, the user email is not registered
s_userDontExist

When requesting to delete a user's access to a particular entity, this user access may not exist
pwdCharacterMin

The password chosen should be at least 6 characters long