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 or accesskey Contains your authentication method.
email/uidThe 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

Postman example

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 or accesskey 
Contains your authentication method.
emailThe 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).
nameThe full name of the user (optional).
organizationThe user's organization (optional).
deptThe user's organization department (optional).
countryThe user's country (optional).
infoAny additional information (optional).
pwdA password to set for the new user (optional).
libidThe library ID.
catidThe category ID, in case the user will have permission over a certain category. This variable is available for libraries only.
bidThe 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).
cidThe 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.
ridThe user role ID, to apply preset permissions for that user (optional).
activeIf 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.
noemailIf value is 1, then no email will be sent to the user. This can't be used if  the active variable is 0.
activationemailIf 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.
expirationdateAn optional date (format: dd-mm-yyyy), to automatically deactivate the user account.
roleexpirationdateAn optional date (format: dd-mm-yyyy), to automatically reset the user's role.
accessexpirationdateAn optional date (format: dd-mm-yyyy), to set the expiration for a certain access (to a book, category, or library). This works only when adding additional access to the user (the uid variable must be passed).

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.

Postman example

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 or accesskey Contains your authentication method.
email/uidThe email or user ID of the existing user.
nameThe full name of the user (optional).
organizationThe user's organization (optional).
deptThe user's organization department (optional).
countryThe user's country (optional).
infoAny 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).
chaptersappendIf 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 .
ridThe 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.
expirationdateAn optional date (format: dd-mm-yyyy), to automatically deactivate the user account.
roleexpirationdateAn optional date (format: dd-mm-yyyy), to automatically reset the user's role.
accessexpirationdateAn optional date (format: dd-mm-yyyy), to set the expiration for a certain access (to a book, category, or library). This works only when passing the id of an entity (i.e. libid, catid, bid).

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

Postman example

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. This endpoint has a limit of 1000 users. Available variables are as follows,

serial or accesskey Contains your authentication method.
libid The library ID.
cid The cloud ebook ID in case you're using a cloud ebook instead of a library.
firstThe index of the first result.

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

Postman example

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 or accesskey Contains your authentication method.
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.
cidThe 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.
deleteallIf 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

Postman example

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 or accesskey Contains your authentication method.
email The email of the existing user.
libid The library ID you're targeting.
cidThe 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

Postman example

Error codes

The API may return the following error codes depicting various meanings
s_authErrorThe serial number or access key used is not registered with Kotobee Cloud.
s_wrongUserThe 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_emailAlreadyRegisteredWhen adding a new user, the email is already registered.
s_userNotRegisteredWhen requesting an edit or delete operation, the user email is not registered.
s_userDontExistWhen requesting to delete a user's access to a particular entity, this user access may not exist.
pwdCharacterMinThe password chosen should be at least 6 characters long.