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
name
The full name of the user (optional)
organization
The user's organization (optional)
dept
The user's organization department (optional)
country
The user's country (optional)
info
Any additional information (optional)
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
rid
The user role ID, to apply preset permissions for that user (optional)
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
name
The full name of the user (optional)
organization
The user's organization (optional)
dept
The user's organization department (optional)
country
The user's country (optional)
info
Any additional information (optional)
pwd 
A password to reset for the new user (optional)
uidThe 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
rid
The user role ID, to apply preset permissions for that user (optional)
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