Share:
ClickHelp Documentation

API: User Management

With the user management functions, you can automate many operations related to setting up Restricted Access to your documentation portal. Available operations are documented below.

User management requests list:


Create a Power Reader

POST Request Create a Power Reader
/api/v1/users HTTP/1.1 

Creates a new Power Reader user account with the specified parameters.

Authorization

This request is using basic authentication.

Request parameters

Request body

A JSON object is sent in the request body containing all necessary parameters.

Field Type Description

userName

required

String (required)

The login name of the Power Reader user to be created.

userInfo

required

Object (required)

User profile information object.

    email

   required

String (required) 

User e-mail address.

    firstName

   required

String (required) 

User first name.

    middleName

   optional

String  User middle name.

    lastName

   optional

String  User last name.

userRole

optional

String One or more Power Reader roles (comma-separated). Roles define the reader's permissions. If the role is not specified, the Power Reader will not be able to access any publications until you set up this user's permissions manually in your ClickHelp portal.

isDontSendEmail

optional

Boolean Defines whether the user will get an e-mail with the automatically generated password. Note that passwords are not stored in the system in plain text due to security considerations. So if you set this parameter to true, the user will not be able to access the system until the password is reset by an administrator or restored via the Forgot Password link on the login page.

Request example

Below, is an example of a CURL command line you can use in a batch file to create a new Power Reader.

Code
curl -X POST ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--header "Content-Type:application/json" ^
-d "{ \"userName\": \"NewPowerReader\", \"userInfo\": {\"email\": \"power-reader@company.co\", \"firstName\": \"John\", \"middleName\": \"M\", \"lastName\": \"Doe\"}, \"userRole\": \"Role1\", \"isDontSendEmail\": false}" ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/users

Response codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

201: Created

A new Power Reader account has been successfully created. The response body is empty. 

409: Conflict

User creation failed - a user with the same name already exists.

Read Power Reader Data

GET Request Read Power Reader data
/api/v1/users/{userName} HTTP/1.1 

Retrieves information on a Power Reader with the specified user name.

Authorization

This request is using basic authentication.

Request parameters

Path parameters

userName

required

string The user name of the Power Reader to get the data about.


Request example

Below, is an example of a CURL command line you can use in a batch file to get the profile data of a Power Reader.

Code
curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/users/NewPowerReader

Response example

JSON
{
"userName":"john.doe",


"userInfo": {
"email":"someone@example.com",
"firstName":"John",
"middleName":"M",


"lastName":"Doe"
},
"userRole": null,
"isEnabled": true
}

Response fields

Field Type Description
userName String

The login name of the Power Reader.

userInfo Object

User profile information object.

    email String

User e-mail address.

    firstName

String

User first name.

    middleName String  User middle name.
    lastName String  User last name.
userRole String

One or more Power Reader Roles (comma-separated) that define the permissions and the ability to access specific Publications for the reader.


Note: Even if this value is null, it is still possible that the user has access permissions assigned directly and can access some publications. Currently, information on such permissions cannot be retrieved via API and available in the application's UI only.

isEnabled Boolean True if the user account is enabled and the user can log in to the portal.


Response codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

200: OK

Returned if the information was retrieved successfully. The response body contains the data.

400: Bad Request

Returned if the specified user is not a Power Reader.

404: Not Found

Returned if a user with the specified name does not exist.

Change a Power Reader Profile

DELETE Request Change a Power Reader profile
/api/v1/users/{userName} HTTP/1.1 

Updates a Power Reader user profile.

Authorization

This request is using basic authentication.

Request parameters

Path parameters

userName

REQUIRED

stringThe user name of the Power Reader.

Request body

A JSON object is sent in the request body containing all necessary parameters.

Field Type Description
updatedFields String

A comma-separated list of field names updated. If a field name is not in the list, it will not be updated even if the field value is specified in other request parameters.

email String

User e-mail address.

userRole String

The Power Reader Role defining the permissions.

isEnabled Boolean Defines whether the user account is enabled and the user is allowed to log in to the portal.

Request example

Below, is an example of a CURL command line you can use in a batch file to change the role assigned to a Power Reader.

Code
curl -X PATCH ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--header "Content-Type:application/json" ^
-d "{\"updatedFields\": \"userRole\", \"userRole\": \"Role2\"}" ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/users/NewPowerReader

Response codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

200: OK

Returned if no user properties were updated.

 204: No Content

Returned if the changes have been applied successfully. The response body is empty.

 400: Bad Request

Returned if the specified user is not a Power Reader.

404: Not Found

Returned if a user with the specified user name does not exist.

Get Authentication Token 

GET Request Get authentication token
/api/v1/users/{userName}/tokens?exp={expirationDate}&muse={multiUse} HTTP/1.1 

Authentication tokens can be used to implement a custom authentication scheme when standard SSO is not an option, but it is necessary to bypass the ClickHelp login screen and seamlessly authenticate users of a third-party application or website in ClickHelp.

A token is a unique string that can be specified as a Login page URL parameter to log in as a specific Power Reader. Tokens are created per your request and each token has an expiration date which you specify when creating the token. For security reasons, we recommend that you generate tokens only when a user is going to access the ClickHelp portal and set small expiration intervals for the tokens.

Request parameters

Path parameters

userName

required

string The login name of the Power Reader.

expirationDate

optional

string
Token expiration date: timestamp string in the ISO 8601 format, in the GMT
timezone. The default value is 30 minutes ahead of the current moment. 

multiUse

optional

boolean
Defines whether the token should expire after the first usage. If set to false (default), the token is expired after the first usage. If set to true, the token can be used multiple times until the expiration date and time comes.

Request example

Below, is an example of a CURL command line you can use in a batch file to get the token for a Power Reader.

Code
curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://kb.clickhelp.co/api/v1/users/NewPowerReader/tokens?exp=2021-12-07T12:11:47Z&muse=true

Response example

JSON
{
"userName": "john.doe",
"token": "kjshd78Dkljod66DsD0Ddsal2l33pa1d",
"expirationDate": "2021-12-07T12:11:47Z",
"multiUse": "true"
}

Response fields

Field Type Description
userName
String The login name of the Power Reader.
token
String The login token to authenticate the Power Reader.
expirationDate
String
The date and time of the moment when the token will expire in the ISO 8601 format (UTC).
multiUseBooleanThe flag defines whether the token can be used multiple times.


Response codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

200: OK

The request has succeeded, the response body contains the requested information.

 400: Bad Request

Returned if the specified user is not a Power Reader.

403: Forbidden

Returned if the authenticated user does not have permission to generate login tokens.

404: Not Found

Returned if a user with the specified name does not exist.

 409: Conflict

Returned if the expiration date specified as a parameter is in the past.