Learn how to add, edit and delete users using Kotobee API. The User API lets you control all of the user aspects for your cloud ebook or library, such as adding, editing, and deleting users.

Please make sure you read the Kotobee API Introduction before starting out here.

Get user

This URL base API (https://www.kotobee.com/api/v1/user/get) retrieves information about a specific user, including his full list of permissions. Available variables are as follows,         

serial 
Contains your serial number.
email/uid
The email or user ID of the existing user.
libid 
The library ID.
cid 
The cloud ebook ID in case you're using a cloud ebook instead of a library.
bidIn case you would like to test this user's permissions against a certain library ebook, this variable will hold the ebook's ID. The response will show a variable named "bookAccess" which will describe the access as being either full, none, or partial. If access is partial, the list the permitted chapters for that user to view will also be sent.

This endpoint is useful to determine whether you will use the /user/add or /user/edit endpoint to update user's access to a specific book. If the permission is already existing, and you'll just need to update the permitted chapters, then you will just need to use the /user/edit endpoint.\

Here's an example of a URL that retrieves the information of a user with ID 100 in a library (ID 21), while testing his permissions against a book with ID 50:
https://www.kotobee.com/api/v1/user/get?serial=1234-5678-9999-9999&uid=100&libid=21&bid=50

Add user

Using the URL base API (https://www.kotobee.com/api/v1/user/add) adds a new user to the system, or adds additional access to an existing user. Available variables are as follows,

serial
Contains your serial number.
email
The email of the new user.
uid

User ID. You may use the user ID instead of the email only if you would like to add additional access to an existing use (optional).
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).
libid
The library ID.
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.
chaptersIf the user will receive permissions over a certain book (either library ebook or cloud ebook), you may specify the chapter indices that the user can only access. Leaving this blank (but still passing the variable) will give access to the entire book (optional).
cid
The cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the 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.
favIf value is 1 and a book ID (bid) is passed, then the book will be automatically added to the user's favorite list.
noemail
If value is 1, then no email will be sent to the user. This can't be used if  the 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 on how to add a user by email (newuser@gmail.com), set a password (mysecretpwd), activate the account, and assign 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


This is an example on 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

This URL base API (https://www.kotobee.com/api/v1/user/edit ) edits an existing user. Available variables are below.

To add book access to an existing user, the /user/add endpoint should be used instead.       

serial 
Contains your serial number.
email/uid
The email or user ID 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).
libid 
The library ID.
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.
chaptersIf the user will receive permissions over a certain book (either library ebook or cloud ebook), you may specify the chapter indices that the user can only access. Leaving this blank (but still passing the variable) will give access to the entire book (optional).
chaptersappend
If the chapters variable is passed, you can control whether to append those list of chapters to the user's current accessed chapters, or to overwrite them. The default behavior is to overwrite them (optional).
cid 
The cloud ebook ID to manage cloud ebooks instead of libraries. In case this is sent, none of the 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.
favIf value is 1 and a book ID (bid) is passed, then the book will be automatically added to the user's favorite list
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 of a URL that deactivates a user from the system:
https://www.kotobee.com/api/v1/user/edit?serial=1234-5678-9999-9999&email=existinguser@gmail.com&libid=10active=0


List users

This URL base API (https://www.kotobee.com/api/v1/user/all) lists all users for a certain cloud ebook or library, along with their details. Available variables are as follows,         

serial 
Contains your serial number.
libid 
The library ID.
cid 
The cloud ebook ID in case you're using a cloud ebook instead of a library.

Here's an example of a URL that lists all users in a cloud ebook with ID 450:
https://www.kotobee.com/api/v1/user/all?serial=1234-5678-9999-9999&cid=450

Delete user

 This URL base API ( https://www.kotobee.com/api/v1/user/delete ) deletes an existing user entirely, or removes 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 of a URL that deletes the user entirely:
http://www.kotobee.com/api/v1/user/delete?serial=1234-5678-9999-9999&email=existinguser@gmail.com&deleteall=1

Clear devices

 This URL base API ( https://www.kotobee.com/api/v1/user/cleardevices ) clears the device list of an existing user, such that he may login from a new set of devices, not surpassing the device (DRM) limit set by you. Available variables are as follows,

serial 
Contains your serial number.
email 
The email of the existing user.
libid 
The library ID you're targeting.
cid
The cloud ebook ID in case the asset in question is a cloud ebook. In this case the libid variable won't take effect.

Here's an example of a URL that deletes the user entirely:
http://www.kotobee.com/api/v1/user/cleardevices?serial=1234-5678-9999-9999&email=existinguser@gmail.com&libid=98

Error codes

The API may return the following error codes depicting various meanings
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_emailBlankNo email was provided when adding a new user.
s_userIdMissingNo 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.